REST Resource: projects.locations.investigations

Recurso: investigação

Contém o conteúdo de uma investigação de solução de problemas do Gemini Cloud Assist.

Representação JSON 
{
  "name": string,
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  },
  "revision": string,
  "revisionIndex": integer,
  "revisionPredecessor": string,
  "annotations": {
    object (InvestigationAnnotations)
  },
  "executionState": enum (InvestigationExecutionState),
  "error": {
    object (Status)
  },
  "operation": string,
  "title": string,
  "observations": {
    string: {
      object (Observation)
    },
    ...
  },
  "observerStatuses": {
    string: {
      object (ObserverStatus)
    },
    ...
  }
}
Campos
name

string

Identificador. Nome da investigação, no formato: projects/{projectNumber}/locations/{locationId}/investigations/{investigationId}
createTime

string (Timestamp format)

Apenas saída. O horário em que a investigação foi criada.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateTime

string (Timestamp format)

Apenas saída. O horário em que a investigação foi atualizada pela última vez.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
labels

map (key: string, value: string)

Opcional. Rótulos definidos pelo usuário para a investigação.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
revision

string

Apenas saída. Nome do recurso da revisão atual da investigação, no formato: projects/{projectNumber}/locations/{locationId}/investigations/{investigationId}/revisions/{revision_id}
revisionIndex

integer

Apenas saída. Índice da revisão atual da investigação.
revisionPredecessor

string

Opcional. O nome da revisão que foi a predecessora desta.
annotations

object (InvestigationAnnotations)

Opcional. Anotações adicionais na investigação.
executionState

enum (InvestigationExecutionState)

Apenas saída. O estado de execução da investigação.
error

object (Status)

Apenas saída. O erro se a execução da investigação falhar. Esse campo só será definido se executionState for INVESTIGATION_EXECUTION_STATE_FAILED.
operation

string

Apenas saída. O nome do recurso da operação "Run" realizada mais recentemente na investigação, no formato: projects/{projectNumber}/locations/{locationId}/operations/{operation_id}
title

string

Opcional. Título de exibição legível por humanos para a investigação.
observations

map (key: string, value: object (Observation))

Opcional. Observações sobre o estado do projeto que compõem o conteúdo da investigação.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
observerStatuses

map (key: string, value: object (ObserverStatus))

Opcional. Status dos observadores que foram invocados para executar a investigação.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

InvestigationAnnotations

Anotações adicionais em uma investigação.

Representação JSON 
{
  "supportCase": string,
  "revisionLastRunInterval": {
    object (Interval)
  },
  "pagePath": string,
  "extrasMap": {
    string: string,
    ...
  }
}
Campos
supportCase

string

Opcional. Um ID de caso de suporte associado à investigação.
revisionLastRunInterval

object (Interval)

Apenas saída. O intervalo em que a investigação foi executada pela última vez.
pagePath

string

Opcional. O caminho de uma página da Web em que esta investigação foi criada.
extrasMap

map (key: string, value: string)

Opcional. Anotações adicionais especificadas pelo cliente.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Intervalo

Representa um intervalo de tempo, codificado como um início de carimbo de data/hora (incluído) e um fim de carimbo de data/hora (não incluído).

O início precisa ser menor ou igual ao fim. Quando o início é igual ao fim, o intervalo fica vazio (não corresponde a nenhum horário). Quando o início e o fim não são especificados, o intervalo corresponde a qualquer momento.

Representação JSON 
{
  "startTime": string,
  "endTime": string
}
Campos
startTime

string (Timestamp format)

Opcional. Início inclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser igual ou posterior ao início.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
endTime

string (Timestamp format)

Opcional. Fim exclusivo do intervalo.

Se especificado, um carimbo de data/hora correspondente a esse intervalo precisará ser anterior ao fim.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

InvestigationExecutionState

O estado de execução de uma investigação.

Enums
INVESTIGATION_EXECUTION_STATE_UNSPECIFIED Valor padrão. Esse valor não é usado.
INVESTIGATION_EXECUTION_STATE_RUNNING A investigação está sendo executada.
INVESTIGATION_EXECUTION_STATE_MODIFIED A investigação ainda não foi executada desde a última atualização.
INVESTIGATION_EXECUTION_STATE_FAILED A execução da investigação foi concluída, mas falhou.
INVESTIGATION_EXECUTION_STATE_COMPLETED Todas as tarefas de execução foram concluídas, e a investigação está inativa.

Observação

Uma observação representa um único fato sobre o estado do sistema em investigação, além de um ranking de relevância.

Representação JSON 
{
  "id": string,
  "timeIntervals": [
    {
      object (Interval)
    }
  ],
  "title": string,
  "observationType": enum (ObservationType),
  "observerType": enum (ObserverType),
  "text": string,
  "data": {
    object
  },
  "dataUrls": {
    string: string,
    ...
  },
  "knowledgeUrls": {
    string: string,
    ...
  },
  "baseObservations": [
    string
  ],
  "relevantResources": [
    string
  ],
  "recommendation": string,
  "systemRelevanceScore": number,
  "relevanceOverride": enum (UserRelevance),
  "observationCompletionState": enum (ObservationCompletionState),
  "observedNormalOperation": boolean
}
Campos
id

string

Apenas saída. Identifica exclusivamente esta observação. Esse valor é sempre igual à chave do mapa dessa observação na investigação principal.
timeIntervals[]

object (Interval)

Opcional. Quando essa observação ocorreu.
title

string

Opcional. Título de exibição legível por humanos para a observação.
observationType

enum (ObservationType)

Obrigatório. O tipo da observação.
observerType

enum (ObserverType)

Obrigatório. O tipo de observador que produziu essa observação.
text

string

Opcional. Texto em linguagem natural ou markdown que explica a observação.
data

object (Struct format)

Opcional. Uma representação estruturada da observação. Isso não é obrigatório nem tem garantia de conformidade com um esquema específico.
dataUrls

map (key: string, value: string)

Opcional. URLs que apontam para evidências em apoio a essa observação. Mapeia de uma descrição legível para um URL.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
knowledgeUrls

map (key: string, value: string)

Opcional. URLs que apontam para conhecimento de referência relacionado a essa observação. Mapeia de uma descrição legível para um URL.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.
baseObservations[]

string

Opcional. Os IDs de outras observações em que esta se baseia. Por exemplo, uma observação de hipótese vai registrar as observações que apoiam essa hipótese.
relevantResources[]

string

Opcional. Os recursos do Google Cloud relevantes para a observação. Eles precisam ser URIs de recursos totalmente qualificados, por exemplo: "//compute.googleapis.com/projects/my-project/zones/us-central1-a/instances/my-instance".
recommendation

string

Opcional. Texto em linguagem natural ou markdown que descreve uma ação recomendada para corrigir a causa raiz ou investigar melhor o problema.
systemRelevanceScore

number

Opcional. A relevância que o observador atribui a essa observação. Isso é usado para classificar observações na geração de hipóteses. O sistema gera observações no intervalo [-1, 1], em que -1 significa completamente irrelevante, 0 significa neutro e 1 significa confiança total na relevância.
relevanceOverride

enum (UserRelevance)

Opcional. O julgamento de relevância do usuário.
observationCompletionState

enum (ObservationCompletionState)

Opcional. Representa se a observação está totalmente formada e pode ser usada para tirar conclusões.
observedNormalOperation

boolean

Opcional. Se for "false" ou não especificado, essa observação vai apresentar informações sobre um problema ou causa raiz. Se for "true", essa observação indica que um sistema estava operando normalmente. Esses resultados negativos podem ser descobertas de diagnóstico úteis, e esse campo não tem correlação com a pontuação de relevância.

ObservationType

Representa o tipo de dados que constituem uma observação. Isso é independente de origem: um registro pode ser fornecido explicitamente pelo usuário, extraído por IA ou identificado por um runbook.

Tipos enumerados
OBSERVATION_TYPE_UNSPECIFIED Valor padrão.
OBSERVATION_TYPE_CLOUD_LOG O texto dessa observação é uma entrada de registro.
OBSERVATION_TYPE_CLOUD_METRIC O conteúdo dessa observação é uma métrica ou um grupo de métricas.
OBSERVATION_TYPE_CAIS_CONFIG Uma configuração
OBSERVATION_TYPE_CAIS_CONFIG_DIFF Uma mudança de configuração
OBSERVATION_TYPE_CLOUD_ALERT Um alerta.
OBSERVATION_TYPE_CICD_EVENT Um evento de um sistema de integração contínua, por exemplo, falha de sondagem.
OBSERVATION_TYPE_TEXT_DESCRIPTION Entrada de texto livre, como a entrada inicial do usuário. Pode ser markdown.
OBSERVATION_TYPE_HYPOTHESIS Usada para conclusões [provisórias] extraídas pelo sistema. Elas podem se tornar entradas para uma revisão subsequente. Nesse caso, as recomendações serão usadas, mas não a correção.
OBSERVATION_TYPE_STRUCTURED_INPUT Entrada estruturada, por exemplo, parâmetros de runbook inseridos em um formulário.
OBSERVATION_TYPE_COMPOSITE Usado para uma observação que inclui mais de um tipo de evidência, como uma saída de runbook.
OBSERVATION_TYPE_OTHER A saída do runbook pode ser "other" se nenhum dos outros tipos se aplicar.
OBSERVATION_TYPE_LOG_THEME Um tema descoberto nos registros.
OBSERVATION_TYPE_CONFIG_ANALYSIS Saída de indicadores que inclui uma configuração analisada por LLM.
OBSERVATION_TYPE_OUTAGE Saída de indicadores que inclui uma interrupção do PSH.
OBSERVATION_TYPE_KNOWLEDGE Texto que apresenta conhecimento sobre o problema de um usuário específico. Por exemplo, instruções do catálogo de erros/links externos, RAG etc.

ObserverType

Isso representa como os dados entraram na investigação.

Tipos enumerados
OBSERVER_TYPE_UNSPECIFIED Valor padrão. Não utilizado.
OBSERVER_TYPE_DIAGNOSTICS Os diagnósticos têm uma noção explícita de causas raízes, por exemplo, usando runbooks.
OBSERVER_TYPE_SIGNALS Os indicadores são para processamento que não tem causas raízes explícitas.
OBSERVER_TYPE_DETERMINISTIC_CODE Isso é para código que depende apenas de instalações. Em especial, pesquisas no catálogo de erros.
OBSERVER_TYPE_AI Isso é para inferências de IA que dependem apenas de observações listadas como premissas.
OBSERVER_TYPE_USER Observação da entrada do usuário, incluindo respostas a esclarecimentos. Todas as observações especificadas pelo usuário serão convertidas para esse tipo.
OBSERVER_TYPE_ALERT Uma observação de um alerta.

UserRelevance

Representa a relevância de uma observação expressa pelo usuário.

Tipos enumerados
USER_RELEVANCE_UNSPECIFIED O usuário não marcou essa observação como relevante ou irrelevante.
USER_RELEVANCE_PROMOTED O usuário marcou essa observação como relevante.
USER_RELEVANCE_REJECTED O usuário marcou essa observação como irrelevante.

ObservationCompletionState

Determina se a observação está totalmente formada e completa.

Tipos enumerados
OBSERVATION_COMPLETION_STATE_UNSPECIFIED Valor padrão. Será tratado como "COMPLETE".
OBSERVATION_COMPLETION_STATE_COMPLETE Essa observação está totalmente formada.
OBSERVATION_COMPLETION_STATE_INCOMPLETE Essa observação não tem todas as informações ou precisa de mais processamento por outro observador. Esse tipo de observação pode ser descartado em execuções futuras de investigações.

ObserverStatus

Um ObserverStatus representa o status de um observador em um determinado momento durante a execução de uma investigação.

Representação JSON 
{
  "observer": string,
  "observerExecutionState": enum (ObserverExecution),
  "observerDisplayName": string,
  "updateTime": string,
  "startTime": string,
  "updateComment": string,
  "observerErrors": [
    {
      object (Status)
    }
  ]
}
Campos
observer

string

Apenas saída. Identifica exclusivamente este observador. Esse valor é sempre igual à chave do mapa deste observador na investigação principal.
observerExecutionState

enum (ObserverExecution)

Opcional. O estado de execução atual do observador.
observerDisplayName

string

Obrigatório. Nome de exibição legível para o observador.
updateTime

string (Timestamp format)

Opcional. O horário em que o observador atualizou a investigação pela última vez. Se o observerExecutionState for "COMPLETE" ou "FAILED", esse será o horário em que o observador terminou a observação.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
startTime

string (Timestamp format)

Opcional. O horário em que o observador começou a observação.

Usa o padrão RFC 3339, em que a saída gerada é sempre convertida em Z e tem 0, 3, 6 ou 9 dígitos fracionários. Além de Z, outros ajustes também são aceitos. Exemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".
updateComment

string

Opcional. Uma atualização de status do observador.
observerErrors[]

object (Status)

Opcional. Um erro que impediu um observador de fazer uma anotação específica.

ObserverExecution

O estado do observador.

Enums
OBSERVER_EXECUTION_UNSPECIFIED O estado do observador não foi especificado.
OBSERVER_EXECUTION_NOT_STARTED A investigação ainda não começou.
OBSERVER_EXECUTION_RUNNING A investigação está em andamento, e este observador pode ser executado ou está em execução.
OBSERVER_EXECUTION_COMPLETE O observador terminou sem um erro interno.
OBSERVER_EXECUTION_FAILED O observador tentou ser executado, mas falhou devido a um erro. Isso é específico de um componente e pode ser renderizado na interface se a observação for mostrada como de prioridade muito baixa.
OBSERVER_EXECUTION_BLOCKED O observador fica bloqueado até receber uma entrada.
OBSERVER_EXECUTION_INVESTIGATION_BLOCKED O observador informa um erro que bloqueia ou afeta gravemente a investigação, por exemplo, CAIS ou registro desativado. Precisa ser renderizado em destaque na interface.
OBSERVER_EXECUTION_INVESTIGATION_DEGRADED O observador informa um erro que prejudica a investigação e pode exigir que o usuário encaminhe ou execute novamente a investigação depois de atenuar a causa.

Métodos

create

 Cria uma nova investigação em um projeto específico.

delete

 Exclui uma única investigação.

get

 Recebe detalhes de uma única Investigação.

getIamPolicy

 Busca a política de controle de acesso de um recurso.

list

 Lista as investigações em determinado projeto e local.

patch

 Atualiza os parâmetros de uma única Investigação.

setIamPolicy

 Define a política de controle de acesso no recurso especificado.

testIamPermissions

 Retorna permissões do autor da chamada no recurso especificado.