Criar uma investigação do Gemini Cloud Assist

Google Cloud

Nesta página, mostramos como criar e analisar investigações do Gemini Cloud Assist.

Antes de começar

  1. Verifique se você configurou o Gemini Cloud Assist.

  2. (Opcional) Verifique se você ativou as APIs recomendadas:

    • logging.googleapis.com
    • monitoring.googelapis.com
    • cloudresourcemanager.googleapis.com

    Consulte Como ativar e desativar serviços para instruções sobre como ativar APIs.

  3. Para receber as permissões necessárias para criar uma investigação, peça para o administrador conceder a você o papel do IAM de Criador de investigações (roles/geminicloudassist.investigationCreator) no projeto.

    Esse papel predefinido contém a permissão necessária para criar uma investigação no projeto. Ao criar uma investigação, você recebe o papel do IAM de Proprietário da investigação (roles/geminicloudassist.investigationOwner) nela, o que permite analisar os resultados.

  4. Ter acesso ao produto em investigação.

    Quando você faz uma investigação, o Gemini Cloud Assist usa suas credenciais para acessar APIs e informações. Isso significa que o acesso da investigação é limitado ao seu acesso.

  5. Se você planeja fazer uma investigação em um aplicativo, ele precisa estar contido em uma pasta configurada para gerenciamento de aplicativos. O Gemini Cloud Assist não oferece suporte a aplicativos criados em um projeto host ou em um limite de projeto único.

Criar uma investigação

Console

  1. Para criar uma nova investigação, clique no botão Investigar associado ao seu ponto de entrada. Um ponto de entrada típico para criar uma investigação é a página Investigações do Cloud Assist.

    Acessar as investigações do Cloud Assist

  2. Expanda o menu suspenso Configurar investigação.

  3. (Opcional) Insira um Nome da investigação.

    O nome escolhido identifica essa investigação no histórico de investigações. Se você pular essa etapa, um nome será gerado automaticamente para a investigação.

  4. Use o menu suspenso Selecionar período para escolher o período que você quer investigar.

    Um horário de início preciso permite fazer correlações com base no tempo entre eventos aparentemente não relacionados e aumenta a importância dos eventos que ocorreram perto do horário de início. Se você não tiver certeza do período, execute várias investigações simultaneamente com períodos diferentes.

  5. Descreva o problema que você está enfrentando.

    Você pode copiar e colar a mensagem de erro exata que recebeu, usar linguagem natural para explicar o problema que está enfrentando ou incluir as duas opções.

  6. Se as investigações de aplicativos forem compatíveis com seu ponto de entrada, use o campo Aplicativo para escolher um aplicativo a ser investigado.

  7. (Opcional) Clique em + Adicionar recurso para selecionar os recursos que são afetados pelo problema que você está enfrentando.

    É possível adicionar recursos usando o seletor ou inserindo-os manualmente. Ao inserir recursos manualmente, consulte a documentação de referência do recurso para garantir que você está usando o formato correto.

    Não é possível continuar uma investigação se você incluir qualquer um dos seguintes itens:

    • Recursos que estão em um projeto ou aplicativo fora do escopo da investigação.
    • Recursos que não são compatíveis.
    • Recursos que não são reconhecidos.

  8. Clique em Criar para iniciar a investigação.

A página Detalhes da investigação é aberta, e os resultados aparecem nela à medida que ficam disponíveis. A investigação pode levar vários minutos para ser concluída. Se você sair da página de detalhes da investigação, poderá verificar o status dela clicando no botão Notificações ().

API

  1. Crie um arquivo JSON com as informações a seguir:

    {
"title": "INVESTIGATION_NAME",
"observations": {
  "user.project": {
    "id": "user.project",
    "observationType": "OBSERVATION_TYPE_STRUCTURED_INPUT",
    "observerType": "OBSERVER_TYPE_USER",
    "text": "PROJECT_NAME"
  },
  "user.input.text": {
    "id": "user.input.text",
    "observationType": "OBSERVATION_TYPE_TEXT_DESCRIPTION",
    "observerType": "OBSERVER_TYPE_USER",
    "timeIntervals": [
      {
        "startTime": "ISSUE_START_TIME"
      }
    ],
    "text": "ISSUE_DESCRIPTION",
    "relevantResources": [
      "AFFECTED_RESOURCE"
    ],
  },
}

    Substitua:

    • INVESTIGATION_NAME: insira um nome para a investigação. Por exemplo, Missing Cloud Storage bucket.

    • PROJECT_NAME: insira o nome do projeto em que a investigação está sendo criada. Por exemplo, my-project.

    • ISSUE_START_TIME: insira a data e a hora em que o problema que você está investigando começou. Por exemplo, 2025-07-08T17:23:00Z.

    • ISSUE_DESCRIPTION: insira uma descrição do problema que você está enfrentando. Você pode incluir a mensagem de erro exata que recebeu, usar linguagem natural para explicar o problema que está enfrentando ou incluir as duas opções.

    • AFFECTED_RESOURCE: insira o nome do recurso envolvido no problema que você está enfrentando. Por exemplo, //storage.googleapis.com/my-bucket. Para garantir que você use o formato correto de um recurso, consulte a documentação de referência dele.

    Para uma representação completa de um recurso de investigação, consulte a especificação de recursos.

  2. Adquira um token de acesso.

    TOKEN=$(gcloud auth print-access-token)

  3. Use o método investigations.create para criar a investigação:

    curl -X POST --data-binary @JSON_FILE_NAME \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  "https://geminicloudassist.googleapis.com/v1alpha/projects/PROJECT_NAME/locations/global/investigations"

    Substitua:

    • JSON_FILE_NAME: insira o caminho para o arquivo JSON criado anteriormente. Por exemplo, Desktop/my-investigation.json.

    • PROJECT_NAME: insira o mesmo nome de projeto que você incluiu na observação user.project.

  4. Na resposta, copie o valor no parâmetro revision.

  5. Use o método investigations.revisions.run para executar a investigação:

    curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "https://geminicloudassist.googleapis.com/v1alpha/projects/REVISION_RESOURCE:run"

    Substitua REVISION_RESOURCE pelo valor que você copiou do parâmetro revision.

A investigação pode levar vários minutos para ser concluída. Para verificar o status da investigação, copie o valor do parâmetro name retornado na resposta investigations.revisions.run e use esse valor no parâmetro name de uma solicitação operations.get.

Analisar uma investigação

Ao trabalhar com investigações no Google Cloud console, você pode conferir os detalhes da investigação no ponto de entrada em que a iniciou ou no histórico de investigações do projeto.

Uma investigação contém as seguintes seções:

  1. O resumo da investigação

    Esta seção contém um resumo de alto nível do problema, a estratégia que o Gemini adotou para investigar e as principais descobertas da investigação.

  2. As hipóteses

    Esta seção contém um ou mais cards de hipóteses com base nos dados coletados e nas observações feitas pela investigação. Para conferir detalhes de cada hipótese, clique no botão Ver no card relevante.

    • Os detalhes de uma hipótese contêm uma seção O que descrevendo o problema e uma seção Próximas etapas descrevendo ações que ajudam a corrigir o problema ou fornecem etapas adicionais de solução de problemas para confirmar ou refutar a hipótese.

      • Se uma correção for compatível com o problema identificado na hipótese, um botão Gerar plano será incluído nas etapas de correção. Ao clicar em Gerar plano , um plano de correção detalhado é criado, incluindo ações concretas, como comandos gcloud ou manifestos do Kubernetes. Depois de analisar o plano, clique em Executar para realizar as ações descritas nele.

  3. As descobertas

    Esta seção contém observações geradas pela investigação e lista os Google Cloud recursos envolvidos nela. As observações são baseadas em análises de runbooks de procedimentos, registros, mensagens de interrupção e alertas.

    A seção de descobertas mostra quais informações o Gemini usou para gerar as hipóteses e pode ser útil para refinar sua investigação.

Você pode revisar a entrada da investigação usando o botão Editar, que permite executar a investigação novamente com informações atualizadas. Quando uma investigação tem várias execuções associadas a ela, é possível analisar os resultados das execuções anteriores usando o seletor suspenso Revisão.

Se você tiver um pacote de suporte, clique no botão Solicitar suporte encontrado na página de detalhes da investigação para registrar um caso de suporte. Ao fazer isso, você pode preencher automaticamente os detalhes do caso e compartilhar os resultados da investigação com o engenheiro de suporte.

A seguir