Criar uma investigação do Cloud Assist

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

Antes de começar

  1. Verifique se o projeto tem as seguintes APIs ativadas:

    • cloudaicompanion.googleapis.com
    • cloudasset.googleapis.com
    • cloudresourcemanager.googleapis.com
    • geminicloudassist.googleapis.com
    • (Recomendado) logging.googleapis.com
    • (Recomendado) monitoring.googelapis.com

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

  2. 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.

  3. 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.

  4. Se você planeja fazer uma investigação em um aplicativo, ele precisa estar em uma pasta habilitada para apps.

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. (Opcional) Insira um Nome para a 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.

  3. 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.

  4. Selecione o Horário de início do problema que você está investigando.

  5. (Opcional) Selecione o Horário de término quando o problema que você está investigando terminar.

  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.

    • Para pontos de entrada que não são compatíveis com investigações de aplicativos, seu projeto atual é listado como o Projeto de destino e não pode ser alterado.

  7. (Opcional) Clique em + Adicionar recurso para selecionar os recursos 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 investigação pode levar vários minutos para ser concluída. Para verificar o status da investigação, clique 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

Quando a investigação for concluída, você poderá conferir os detalhes dela 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 Problema

    Essa seção contém as informações de entrada usadas para gerar os resultados da investigação, como a descrição do problema, carimbos de data/hora e listas de recursos relevantes. Há três tipos de lista de recursos que podem ser associadas à investigação:

    • Recursos fornecidos pelo usuário: recursos fornecidos pelo usuário ou buscados no erro inicial.
    • Recursos descobertos: recursos adicionais considerados pelo Gemini durante a investigação.
    • Recursos relevantes: os recursos que o Gemini considera relevantes para a hipótese de causa raiz, que sempre inclui recursos fornecidos pelo usuário.

  2. As Observações

    Esta seção contém observações geradas pela investigação. As observações são baseadas em análises de runbooks de procedimentos, registros, mensagens de interrupção e alertas. Com base nessas observações, o Gemini gera hipóteses sobre a causa raiz do problema que você está investigando.

  3. As Hipóteses

    Esta seção contém uma ou mais hipóteses com base nos dados coletados e nas observações feitas pela investigação. Uma hipótese contém uma visão geral do que o problema pode ser e correções recomendadas, que são ações que ajudam a corrigir o problema ou fornecem etapas adicionais de solução de problemas para confirmar ou refutar a hipótese.

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.

A seguir