Crie uma investigação do Cloud Assist

Esta página mostra como criar e rever investigações do Gemini Cloud Assist.

Antes de começar

  1. Confirme se o seu 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 o artigo Ativar e desativar serviços para ver instruções sobre como ativar APIs.

  2. Para obter as autorizações necessárias para criar uma investigação, peça ao seu administrador para lhe conceder a função de IAM criador de investigações (roles/geminicloudassist.investigationCreator) no projeto.

    Esta função predefinida contém a autorização necessária para criar uma investigação no seu projeto. Quando cria uma investigação, é-lhe concedida a função de IAM Proprietário da investigação (roles/geminicloudassist.investigationOwner) nessa investigação, o que lhe permite rever os resultados da investigação.

  3. Ter acesso ao produto que está a ser investigado.

    Quando realiza uma investigação, o Gemini Cloud Assist usa as suas credenciais para aceder a APIs e informações. Isto significa que o acesso à investigação está limitado ao acesso que tem.

  4. Se planeia realizar uma investigação numa aplicação, a aplicação tem de estar contida numa pasta com apps ativadas.

Crie uma investigação

Consola

  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.

    Aceda às investigações do Cloud Assist

  2. (Opcional) Introduza um nome para a investigação.

    O nome que escolher identifica esta investigação no seu histórico de investigações. Se ignorar este passo, é gerado automaticamente um nome para a investigação.

  3. Descreva o problema que está a ter.

    Pode copiar e colar a mensagem de erro exata que recebeu, usar linguagem natural para explicar o problema que está a ter ou incluir ambas.

  4. Selecione a Hora de início em que o problema que está a investigar começou.

  5. (Opcional) Selecione a Hora de fim em que o problema que está a investigar terminou.

  6. Se as investigações de aplicações forem suportadas pelo seu ponto de entrada, use o campo Aplicação para escolher uma aplicação a investigar.

    • Para pontos de entrada que não suportam investigações de aplicações, o seu projeto atual é apresentado como o Projeto de destino e não pode ser alterado.

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

    Pode adicionar recursos através do selecionador de recursos ou introduzi-los manualmente. Quando introduz recursos manualmente, deve consultar a documentação de referência do recurso para garantir que usa o formato correto.

    Não pode avançar com uma investigação se incluir qualquer um dos seguintes elementos:

    • Recursos que estão num projeto ou numa aplicação que está fora do âmbito da investigação.
    • Recursos não suportados.
    • Recursos que não são reconhecidos.

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

A conclusão da investigação pode demorar vários minutos. Pode verificar o estado da investigação clicando no botão Notificações ().

API

  1. Crie um ficheiro JSON que contenha as seguintes informações:

    {
"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 o seguinte:

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

    • PROJECT_NAME: introduza o nome do projeto no qual a investigação está a ser criada. Por exemplo, my-project.

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

    • ISSUE_DESCRIPTION: introduza uma descrição do problema que está a ter. Pode incluir a mensagem de erro exata que recebeu, usar linguagem natural para explicar o problema que está a ter ou incluir ambas.

    • AFFECTED_RESOURCE: introduza o nome do recurso envolvido no problema que está a ter. Por exemplo, //storage.googleapis.com/my-bucket. Para garantir que usa o formato correto para um recurso, deve consultar a documentação de referência do recurso.

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

  2. Obtenha uma chave 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 o seguinte:

    • JSON_FILE_NAME: introduza o caminho para o ficheiro JSON que criou anteriormente. Por exemplo, Desktop/my-investigation.json.

    • PROJECT_NAME: introduza o mesmo nome do projeto que 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 copiou do parâmetro revision.

A conclusão da investigação pode demorar vários minutos. Pode verificar o estado da investigação copiando o valor do parâmetro name que foi devolvido na resposta investigations.revisions.run e usando o valor no parâmetro name de um pedido operations.get.

Reveja uma investigação

Quando a investigação estiver concluída, pode ver os detalhes da investigação no ponto de entrada onde a iniciou ou no histórico de investigações do seu projeto.

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

  1. O problema

    Esta secção contém as informações de entrada que foram usadas para gerar os resultados da investigação, como a descrição do problema, as indicações de tempo e as listas de recursos relevantes. Existem três tipos de listas de recursos que podem estar associadas à investigação:

    • Recursos fornecidos pelo utilizador: recursos fornecidos pelo utilizador ou obtidos a partir do 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 da causa principal, que incluem sempre recursos fornecidos pelo utilizador.

  2. As observações

    Esta secção contém observações geradas pela investigação. As observações baseiam-se em revisões de manuais de procedimentos, registos, mensagens de interrupção e alertas. A partir destas observações, o Gemini gera hipóteses quanto à causa principal do problema que está a investigar.

  3. As hipóteses

    Esta secção contém uma ou mais hipóteses baseadas nos dados recolhidos pela investigação e nas observações feitas. Uma hipótese contém uma vista geral do que o problema pode ser e correções recomendadas, que são ações que ajudam a corrigir o problema ou que lhe fornecem passos de resolução de problemas adicionais para confirmar ou refutar a hipótese.

Pode rever a entrada da investigação através do botão Editar, que lhe permite executar novamente a investigação com informações atualizadas. Quando uma investigação tem várias execuções associadas, pode rever os resultados das execuções anteriores da investigação através do seletor de menu pendente Revisão.

O que se segue?