O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Usar a API App Topology

É possível executar consultas de maneira programática para correlacionar dados em Google Cloud usando a API REST ou a Google Cloud CLI.

Visão geral

Quando você executa uma consulta da API App Topology, ela retorna uma lista de nós (recursos) e arestas (relacionamentos) do gráfico que correspondem à consulta. A App Topology combina dados de vários Google Cloud serviços, como:

Metadados de recursos do Inventário de recursos do Cloud, do App Hub e do Agent Registry
Dados de implantação, como um commit do Git ou a procedência do build de uma imagem do contêiner
Dados de segurança do Security Command Center, como vulnerabilidades ou propriedade do Identity and Access Management (IAM)
Dados do Google Cloud Observability, como rastreamentos e alertas

Para executar uma consulta, você precisa das seguintes informações:

O domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis. Consulte listar domínios para saber como listar domínios disponíveis.
Os nós, arestas e propriedades de gráfico compatíveis que podem ser incluídos em uma consulta. Você pode receber o esquema completo ou parcial de um domínio. Para mais detalhes, consulte Receber o esquema.
O padrão de consulta com os nós e as arestas que você quer pesquisar. Consulte Executar consultas.

Antes de começar

Configure a App Topology.
Selecione a guia para como planeja usar as amostras nesta página:
gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.
REST

Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.
Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .
Para informações sobre como configurar a autenticação em um ambiente de produção, consulte Configurar o Application Default Credentials para código executado no Google Cloud na documentação de autenticação do Google Cloud .

Funções exigidas

Para receber as permissões necessárias para usar a API App Topology, peça ao administrador que conceda a você os seguintes papéis do IAM:

Executar consultas: Leitor da App Topology (roles/apptopology.viewer) nos projetos em que você quer usar a App Topology

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Esses papéis predefinidos contêm as permissões necessárias para usar a API App Topology. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As seguintes permissões são necessárias para usar a API App Topology:

Receber domínios:
- apptopology.domains.get
- apptopology.domains.list
Receber esquemas: apptopology.schemas.get
Receber dados de recursos descobertos: apptopology.discoveredResourcesTopologies.generate
Receba dados do domínio de DevOps: apptopology.devOpsDomainTopologies.generate
Receber dados do domínio de segurança: apptopology.securityDomainTopologies.generate
Receber dados do domínio de SRE (todos os dados compatíveis): apptopology.sreDomainTopologies.generate

Essas permissões também podem ser concedidas com funções personalizadas ou outros papéis predefinidos.

Listar domínios

Os domínios são conjuntos de dados de recursos focados em tipos específicos de consultas.

Para consultar todos os dados compatíveis com a Topologia de apps, use o domínio SRE.
Para receber dados sobre recursos de agente, use o domínio SRE.
Todos os exemplos de respostas de solicitação neste documento usam o domínio SRE.

Se necessário, liste os domínios disponíveis em um projeto.

gcloud

Listar domínios

Antes de usar os dados do comando abaixo, faça estas substituições:

PROJECT_ID: o ID do projeto

Execute o comando gcloud app-topology domains list:

Linux, macOS ou Cloud Shell

gcloud app-topology domains list --project=PROJECT_ID

Windows (PowerShell)

gcloud app-topology domains list --project=PROJECT_ID

Windows (cmd.exe)

gcloud app-topology domains list --project=PROJECT_ID

Você receberá uma resposta semelhante a esta

NAME
DEVOPS
SECURITY
SRE

REST

Listar domínios

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto

Método HTTP e URL:

GET https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . Para saber qual é a conta ativa no momento, execute o comando gcloud auth list.

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "domains": [
    {
      "name": "projects/PROJECT_ID/locations/global/domains/DEVOPS"
    },
    {
      "name": "projects/PROJECT_ID/locations/global/domains/SECURITY"
    },
    {
      "name": "projects/PROJECT_ID/locations/global/domains/SRE"
    }
  ]
}

Acessar o esquema

Para ajudar você a criar consultas, é possível receber uma lista de todos os nós, arestas e propriedades compatíveis de um domínio. A API REST também permite receber uma parte do esquema.

As solicitações do esquema completo podem levar muito mais tempo do que as de um esquema parcial devido ao grande número de itens no esquema.

Receber o esquema completo

gcloud

Receber esquema completo

Antes de usar os dados do comando abaixo, faça estas substituições:

PROJECT_ID: o ID do projeto
DOMAIN: o domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis.

Execute o comando gcloud app-topology domains schema describe:

Linux, macOS ou Cloud Shell

gcloud app-topology domains schema describe DOMAIN --project=PROJECT_ID

Windows (PowerShell)

gcloud app-topology domains schema describe DOMAIN --project=PROJECT_ID

Windows (cmd.exe)

gcloud app-topology domains schema describe DOMAIN --project=PROJECT_ID

O exemplo a seguir de um trecho de resposta inclui apenas o primeiro item no esquema para tipos de nós, tipos de arestas, regras de arestas e propriedades de rótulo.

{
  "nodeTypes": [
    {
      "type": "Base/compute.googleapis.com/UrlMap",
      "labels": [
        "Base/Resource",
        "Base/compute.googleapis.com/UrlMap"
      ],
      "description": "Represents a Compute UrlMap."
    }
  ],
  "edgeTypes": [
    {
      "type": "Observability/SENDS_TRAFFIC/Base/geminidataanalytics.googleapis.com/DataAgent:Base/apps.k8s.io/DaemonSet",
      "labels": [
        "Observability/SENDS_TRAFFIC"
      ]
    }
  ],
  "labelProperties": [
    {
      "label": "Base/compute.googleapis.com/InstanceSettings",
      "description": "Classifies a node as a Compute Instance Settings."
    }
  ],
  "edgeRules": [
    {
      "edgeType": "Observability/SENDS_TRAFFIC/Base/geminidataanalytics.googleapis.com/DataAgent:Base/apps.k8s.io/DaemonSet",
      "srcNodeType": "Base/geminidataanalytics.googleapis.com/DataAgent",
      "destNodeType": "Base/apps.k8s.io/DaemonSet"
    }
  ]
}

REST

Receber esquema completo

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto
DOMAIN: o domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis.

Método HTTP e URL:

GET https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema" | Select-Object -Expand Content

O exemplo a seguir de um trecho de resposta inclui apenas o primeiro item no esquema para tipos de nós, tipos de arestas, regras de arestas e propriedades de rótulo.

{
  "nodeTypes": [
    {
      "type": "Base/compute.googleapis.com/UrlMap",
      "labels": [
        "Base/Resource",
        "Base/compute.googleapis.com/UrlMap"
      ],
      "description": "Represents a Compute UrlMap."
    }
  ],
  "edgeTypes": [
    {
      "type": "Observability/SENDS_TRAFFIC/Base/geminidataanalytics.googleapis.com/DataAgent:Base/apps.k8s.io/DaemonSet",
      "labels": [
        "Observability/SENDS_TRAFFIC"
      ]
    }
  ],
  "labelProperties": [
    {
      "label": "Base/compute.googleapis.com/InstanceSettings",
      "description": "Classifies a node as a Compute Instance Settings."
    }
  ],
  "edgeRules": [
    {
      "edgeType": "Observability/SENDS_TRAFFIC/Base/geminidataanalytics.googleapis.com/DataAgent:Base/apps.k8s.io/DaemonSet",
      "srcNodeType": "Base/geminidataanalytics.googleapis.com/DataAgent",
      "destNodeType": "Base/apps.k8s.io/DaemonSet"
    }
  ]
}

Receber um esquema parcial

É possível extrair uma parte de um esquema de domínio dentro de um número especificado de hops de um rótulo inicial especificado.

O comando de exemplo nestas instruções recebe uma parte do esquema começando no nó Base/Agent, com uma profundidade de 1 e um tamanho de página de 5.

Receber esquema parcial

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto
DOMAIN: o domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis.

Método HTTP e URL:

POST https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema:explore

Corpo JSON da solicitação:

{
  "startLabels": [
    "Base/Agent"
  ],
  "depth": 1,
  "pageSize": 5
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "startLabels": [
    "Base/Agent"
  ],
  "depth": 1,
  "pageSize": 5
}EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema:explore"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "startLabels": [
    "Base/Agent"
  ],
  "depth": 1,
  "pageSize": 5
}'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/domains/DOMAIN/schema:explore" | Select-Object -Expand Content

Em uma resposta, a ordem de nodeTypes e edgeTypes é consistente, mas a ordem de labelProperties pode variar de solicitação para solicitação.

Abra o cabeçalho Resposta para ver um exemplo.

Resposta

{
  "nodeTypes": [
    {
      "type": "Base/aiplatform.googleapis.com/Agent",
      "labels": [
        "Base/Resource",
        "Base/aiplatform.googleapis.com/Agent"
      ],
      "description": "Represents an Agents API Agent.",
      "optionalLabels": [
        "Base/Agent"
      ]
    },
    {
      "type": "Base/agentregistry.googleapis.com/Binding",
      "labels": [
        "Base/Resource",
        "Base/agentregistry.googleapis.com/Binding"
      ],
      "description": "Represents an Agent Registry Binding."
    },
    {
      "type": "Base/agentregistry.googleapis.com/Service",
      "labels": [
        "Base/Resource",
        "Base/agentregistry.googleapis.com/Service"
      ],
      "description": "Represents a Agent Registry Service.",
      "optionalLabels": [
        "Base/DiscoveredService",
        "Base/Endpoint",
        "Base/MCPServer",
        "Base/Agent"
      ]
    }
  ],
  "edgeTypes": [
    {
      "type": "Base/REVERSED:agentregistry.googleapis.com/Binding:source.identifier.agent:aiplatform.googleapis.com/Agent",
      "labels": [
        "DEPENDS_ON"
      ]
    },
    {
      "type": "Base/REVERSED:agentregistry.googleapis.com/Binding:source.identifier.agentregistry_service:agentregistry.googleapis.com/Service",
      "labels": [
        "DEPENDS_ON"
      ]
    }
  ],
  "labelProperties": [
    {
      "label": "Base/agentregistry.googleapis.com/Service",
      "description": "Classifies a node as a Agent Registry Service."
    },
    {
      "label": "Base/DiscoveredService",
      "properties": [
        {
          "name": "Base/app/names",
          "stringValue": {
            "repeated": true
          },
          "description": "The full name of the application."
        }
      ],
      "description": "Represents a discovered service from AppHub."
    },
    {
      "label": "Base/Agent",
      "properties": [
        {
          "name": "Base/agentregistry/urn",
          "stringValue": {},
          "description": "Canonical Logical URN of the agent, mcp server or endpoint, generated by the Agent Registry."
        },
        {
          "name": "Base/agent/identity",
          "stringValue": {},
          "description": "Cryptographically verifiable SPIFFE ID of the agent."
        },
        {
          "name": "Base/agent/provenance",
          "stringValue": {},
          "description": "Classification of the agent (e.g. 1P, 2P, 3P)."
        },
        {
          "name": "Base/agent/framework",
          "stringValue": {},
          "description": "The agent framework used (e.g. ADK, LangChain)."
        }
      ],
      "description": "Represents an agent."
    },
    {
      "label": "Base/agentregistry.googleapis.com/Binding",
      "description": "Classifies a node as an Agent Registry Binding."
    },
    {
      "label": "Base/Endpoint",
      "properties": [
        {
          "name": "Base/agentregistry/urn",
          "stringValue": {},
          "description": "Canonical Logical URN of the agent, mcp server or endpoint, generated by the Agent Registry."
        },
        {
          "name": "Base/endpoint/urls",
          "stringValue": {
            "repeated": true
          },
          "description": "List of destination URLs for the endpoint."
        },
        {
          "name": "Base/endpoint/protocolBindings",
          "stringValue": {
            "repeated": true
          },
          "description": "List of protocol bindings for the endpoint interfaces (e.g. JSONRPC, GRPC, HTTP_JSON)."
        }
      ],
      "description": "Represents an endpoint."
    },
    {
      "label": "Base/MCPServer",
      "properties": [
        {
          "name": "Base/agentregistry/urn",
          "stringValue": {},
          "description": "Canonical Logical URN of the agent, mcp server or endpoint, generated by the Agent Registry."
        }
      ],
      "description": "Represents a MCP Server."
    },
    {
      "label": "DEPENDS_ON",
      "description": "Signifies operational necessity. The source has an active functional dependency on the destination that enables the source to run or perform its primary function."
    },
    {
      "label": "Base/Resource",
      "properties": [
        {
          "name": "project",
          "stringValue": {},
          "description": "Project number in the format projects/{project_number}."
        },
        {
          "name": "folders",
          "stringValue": {
            "repeated": true
          },
          "description": "List of folder IDs in the format folders/{folder_id}."
        },
        {
          "name": "organization",
          "stringValue": {},
          "description": "Organization Id in the format organizations/{organization_id}."
        },
        {
          "name": "Base/resourceType",
          "stringValue": {},
          "description": "Type of the resource in the format of service.googleapis.com/ResourceType."
        },
        {
          "name": "Base/location",
          "stringValue": {},
          "description": "Location of the resource."
        },
        {
          "name": "Base/displayName",
          "stringValue": {},
          "description": "Display name of the resource."
        }
      ],
      "description": "Represents a GCP resource."
    },
    {
      "label": "Base/aiplatform.googleapis.com/Agent",
      "description": "Classifies a node as an Agents API Agent."
    }
  ],
  "edgeRules": [
    {
      "edgeType": "Base/REVERSED:agentregistry.googleapis.com/Binding:source.identifier.agent:aiplatform.googleapis.com/Agent",
      "srcNodeType": "Base/aiplatform.googleapis.com/Agent",
      "destNodeType": "Base/agentregistry.googleapis.com/Binding"
    },
    {
      "edgeType": "Base/REVERSED:agentregistry.googleapis.com/Binding:source.identifier.agentregistry_service:agentregistry.googleapis.com/Service",
      "srcNodeType": "Base/agentregistry.googleapis.com/Service",
      "destNodeType": "Base/agentregistry.googleapis.com/Binding"
    }
  ],
  "nextPageToken": "CAIQ6_LBy4mN1ox5GP_s5PGS1ZGY-wE"
}

Execute consultas

Ao executar uma consulta, você especifica um padrão de consulta que inclui os nós, as arestas e as propriedades que quer pesquisar.

Os padrões de consulta são baseados na sintaxe de filtragem AIP-160. Para uma visão geral dos padrões e limitações de consulta, consulte Sobre consultas. Estas instruções pressupõem que você leu as informações sobre estrutura e limitações de consultas.

As instruções a seguir usam uma consulta de exemplo para todos os serviços e cargas de trabalho do App Hub no projeto especificado, incluindo os registrados (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) e os descobertos (Base/DiscoveredService, Base/DiscoveredWorkload).

Os comandos especificam o padrão de consulta em um arquivo JSON. O arquivo é um pouco diferente para a CLI gcloud e solicitações REST nestas instruções.

Para a CLI gcloud, especifique o domínio a ser consultado como um parâmetro do comando. O domínio não está incluído no arquivo de padrão de consulta.
Para solicitações REST, especifique o domínio e o padrão de consulta no corpo JSON da solicitação. Defina o domínio no campo topologyDomains e especifique o padrão de consulta no objeto filter.

gcloud

Gerar topologia

Antes de usar os dados do comando abaixo, faça estas substituições:

PROJECT_ID: o ID do projeto
DOMAIN: o domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis.

Salve o conteúdo a seguir em um arquivo chamado request.json:

{
  "startingNode": {
    "alias": "sw",
    "labelPropertiesPattern": {
      "labelMatcherExpr": "Base/apphub.googleapis.com/Service OR Base/apphub.googleapis.com/Workload OR Base/DiscoveredService OR Base/DiscoveredWorkload"
    }
  }
}

Execute o comando gcloud app-topology resources-graph generate:

Linux, macOS ou Cloud Shell

gcloud app-topology resources-graph generate --domains=DOMAIN --project=PROJECT_ID --pattern-file=request.json --format=json

Windows (PowerShell)

gcloud app-topology resources-graph generate --domains=DOMAIN --project=PROJECT_ID --pattern-file=request.json --format=json

Windows (cmd.exe)

gcloud app-topology resources-graph generate --domains=DOMAIN --project=PROJECT_ID --pattern-file=request.json --format=json

O exemplo a seguir mostra os dois primeiros nós. Esses nós são servidores MCP. Os servidores MCP do Google têm o rótulo Base/DiscoveredService, que é um dos rótulos no padrão de consulta.

Na saída, as seguintes variáveis representam valores associados ao projeto especificado com PROJECT_ID:

PROJECT_NUMBER: o número do projeto especificado.
ORGANIZATION_NUMBER: o número da organização Google Cloud que contém o projeto especificado.

{
  "graph": {
    "nodes": [
      {
        "properties": {
          "project": "projects/PROJECT_NUMBER",
          "Base/location": "global",
          "createTime": "2026-08-13T15:14:53.477680Z",
          "Base/agentregistry/urn": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:storage",
          "Base/resourceType": "agentregistry.googleapis.com/GoogleMcpServer",
          "organization": "organizations/ORGANIZATION_NUMBER"
        },
        "name": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:storage",
        "labels": [
          "Base/MCPServer",
          "Base/DiscoveredService",
          "Base/Resource",
          "Base/agentregistry.googleapis.com/GoogleMcpServer"
        ],
        "context": {
          "type": "Base/agentregistry.googleapis.com/GoogleMcpServer"
        }
      },
      {
        "properties": {
          "createTime": "2026-08-13T16:22:24.732600Z",
          "Base/resourceType": "agentregistry.googleapis.com/GoogleMcpServer",
          "Base/agentregistry/urn": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:pubsub",
          "Base/location": "global",
          "organization": "organizations/ORGANIZATION_NUMBER",
          "project": "projects/PROJECT_NUMBER"
        },
        "name": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:pubsub",
        "labels": [
          "Base/agentregistry.googleapis.com/GoogleMcpServer",
          "Base/Resource",
          "Base/DiscoveredService",
          "Base/MCPServer"
        ],
        "context": {
          "type": "Base/agentregistry.googleapis.com/GoogleMcpServer"
        }
      }
    ]
  }
}

REST

Gerar topologia

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID: o ID do projeto
DOMAIN: o domínio que você quer consultar. O domínio SRE inclui todos os dados compatíveis.

Método HTTP e URL:

POST https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/discoveredResourcesTopology:generate

Corpo JSON da solicitação:

{
  "topologyDomains": [
    "projects/PROJECT_ID/locations/global/domains/DOMAIN"
  ],
  "filter": {
    "startingNode": {
      "alias": "sw",
      "labelPropertiesPattern": {
        "labelMatcherExpr": "Base/apphub.googleapis.com/Service OR Base/apphub.googleapis.com/Workload OR Base/DiscoveredService OR Base/DiscoveredWorkload"
      }
    }
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você tenha feito login na CLI do gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "topologyDomains": [
    "projects/PROJECT_ID/locations/global/domains/DOMAIN"
  ],
  "filter": {
    "startingNode": {
      "alias": "sw",
      "labelPropertiesPattern": {
        "labelMatcherExpr": "Base/apphub.googleapis.com/Service OR Base/apphub.googleapis.com/Workload OR Base/DiscoveredService OR Base/DiscoveredWorkload"
      }
    }
  }
}
EOF

Depois execute o comando a seguir para enviar a solicitação REST:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/discoveredResourcesTopology:generate"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "topologyDomains": [
    "projects/PROJECT_ID/locations/global/domains/DOMAIN"
  ],
  "filter": {
    "startingNode": {
      "alias": "sw",
      "labelPropertiesPattern": {
        "labelMatcherExpr": "Base/apphub.googleapis.com/Service OR Base/apphub.googleapis.com/Workload OR Base/DiscoveredService OR Base/DiscoveredWorkload"
      }
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://apptopology.googleapis.com/v1/projects/PROJECT_ID/locations/global/discoveredResourcesTopology:generate" | Select-Object -Expand Content

O trecho de exemplo de resposta a seguir mostra os dois primeiros nós. Esses nós são servidores MCP. Os servidores MCP do Google têm o rótulo Base/DiscoveredService, que é um dos rótulos no padrão de consulta.

Na saída, as seguintes variáveis representam valores associados ao projeto especificado com PROJECT_ID:

PROJECT_NUMBER: o número do projeto especificado.
ORGANIZATION_NUMBER: o número da organização Google Cloud que contém o projeto especificado.

{
  "graph": {
    "nodes": [
      {
        "properties": {
          "project": "projects/PROJECT_NUMBER",
          "Base/location": "global",
          "createTime": "2026-08-13T15:14:53.477680Z",
          "Base/agentregistry/urn": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:storage",
          "Base/resourceType": "agentregistry.googleapis.com/GoogleMcpServer",
          "organization": "organizations/ORGANIZATION_NUMBER"
        },
        "name": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:storage",
        "labels": [
          "Base/MCPServer",
          "Base/DiscoveredService",
          "Base/Resource",
          "Base/agentregistry.googleapis.com/GoogleMcpServer"
        ],
        "context": {
          "type": "Base/agentregistry.googleapis.com/GoogleMcpServer"
        }
      },
      {
        "properties": {
          "createTime": "2026-08-13T16:22:24.732600Z",
          "Base/resourceType": "agentregistry.googleapis.com/GoogleMcpServer",
          "Base/agentregistry/urn": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:pubsub",
          "Base/location": "global",
          "organization": "organizations/ORGANIZATION_NUMBER",
          "project": "projects/PROJECT_NUMBER"
        },
        "name": "urn:mcp:googleapis.com:projects:PROJECT_NUMBER:locations:global:pubsub",
        "labels": [
          "Base/agentregistry.googleapis.com/GoogleMcpServer",
          "Base/Resource",
          "Base/DiscoveredService",
          "Base/MCPServer"
        ],
        "context": {
          "type": "Base/agentregistry.googleapis.com/GoogleMcpServer"
        }
      }
    ]
  }
}

Para mais exemplos de padrões de consulta, consulte Exemplos de padrões de consulta.

Exemplos de padrões de consulta

Use os exemplos de padrões de consulta a seguir para criar seus próprios padrões de consulta para executar consultas. Todos os exemplos nesta seção usam o formato JSON.

VMs com grupos de instâncias, redes e discos

Consulta de instâncias do Compute Engine em um grupo de instâncias com rede e disco.

O padrão começa em Base/compute.googleapis.com/Instance e tem três ramificações edge principais no objeto neighbors de nível superior que definem esses critérios:

Instâncias que pertencem a um grupo gerenciado de instâncias
Instâncias com uma rede conectada
Instâncias com Persistent Disk

Como as ramificações são combinadas com AND, a resposta inclui apenas instâncias que pertencem a um grupo gerenciado de instâncias e têm uma rede e um disco.

{
  "startingNode": {
    "alias": "instance",
    "labelPropertiesPattern": {
      "labelMatcherExpr": "Base/compute.googleapis.com/Instance"
    }
  },
  "neighbors": [
    {
      "edge": {
        "direction": "FROM",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "CONTAINS"
        }
      },
      "graph": {
        "startingNode": {
          "alias": "instance_group",
          "labelPropertiesPattern": {
            "labelMatcherExpr": "Base/compute.googleapis.com/InstanceGroup"
          }
        },
        "neighbors": [
          {
            "edge": {
              "direction": "FROM",
              "labelPropertiesPattern": {
                "labelMatcherExpr": "DEPENDS_ON"
              }
            },
            "graph": {
              "startingNode": {
                "alias": "instance_group_manager",
                "labelPropertiesPattern": {
                  "labelMatcherExpr": "Base/compute.googleapis.com/InstanceGroupManager"
                }
              }
            }
          }
        ]
      }
    },
    {
      "edge": {
        "direction": "TO",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "DEPENDS_ON"
        }
      },
      "graph": {
        "startingNode": {
          "alias": "network",
          "labelPropertiesPattern": {
            "labelMatcherExpr": "Base/compute.googleapis.com/Network"
          }
        }
      }
    },
    {
      "edge": {
        "direction": "TO",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "DEPENDS_ON"
        }
      },
      "graph": {
        "startingNode": {
          "alias": "disk",
          "labelPropertiesPattern": {
            "labelMatcherExpr": "Base/compute.googleapis.com/Disk"
          }
        }
      }
    }
  ]
}

Recursos agênticos

Consulte recursos de agentes e as relações entre eles usando informações do Agent Registry, incluindo dados de agentes, servidores MCP, endpoints e habilidades.

{
  "startingNode": {
    "alias": "resource",
    "labelPropertiesPattern": {
      "labelMatcherExpr": "Base/Agent OR Base/MCPServer OR Base/agentregistry.googleapis.com/Skill OR Base/agentregistry.googleapis.com/SkillRevision OR Base/agentregistry.googleapis.com/AiApplication OR Base/agentregistry.googleapis.com/GoogleMcpServer OR Base/agentregistry.googleapis.com/McpEnablement OR Base/agentregistry.googleapis.com/Publisher OR Base/agentregistry.googleapis.com/Binding OR Base/agentregistry.googleapis.com/Service OR Base/aiplatform.googleapis.com/Endpoint"
    }
  }
}

O App Topology é compatível com dois tipos de endpoints:

Base/aiplatform.googleapis.com/Endpoint é um endpoint de modelo da Gemini Enterprise Agent Platform.
Base/Endpoint é o URL de destino de um Agent Endpoint e é um rótulo em um serviço do Agent Registry (Base/agentregistry.googleapis.com/Service). Como Base/agentregistry.googleapis.com/Service está incluído no padrão de consulta, os Agent Endpoints são incluídos nos resultados da resposta da consulta.

Tráfego do agente

Consulte o tráfego entre agentes e outros agentes ou servidores MCP usando dados do Cloud Trace. Cada aresta inclui dados de taxa de erro e latência p95.

{
  "startingNode": {
    "alias": "agent",
    "labelPropertiesPattern": {
      "labelMatcherExpr": "Base/Agent"
    }
  },
  "neighbors": [
    {
      "edge": {
        "direction": "ANY",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "Observability/SENDS_TRAFFIC"
        }
      },
      "graph": {
        "startingNode": {
          "alias": "peer",
          "labelPropertiesPattern": {
            "labelMatcherExpr": "Base/Agent OR Base/MCPServer"
          }
        }
      }
    }
  ]
}

A seguir

Saiba como usar o servidor MCP remoto.
Saiba como executar consultas no Cloud Hub.
Aprenda mais sobre como executar consultas na Gemini Enterprise Agent Platform.

Usar a API App Topology Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Visão geral

Antes de começar

gcloud

REST

Funções exigidas

Permissões necessárias

Listar domínios

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Acessar o esquema

Receber o esquema completo

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Receber um esquema parcial

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Resposta

Execute consultas

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Exemplos de padrões de consulta

VMs com grupos de instâncias, redes e discos

Recursos agênticos

Tráfego do agente

A seguir

Usar a API App Topology