Utilizzare l'API App Topology

Puoi eseguire query in modo programmatico per correlare i dati tra Google Cloud utilizzando l'API REST o Google Cloud CLI.

Panoramica

Quando esegui una query dell'API App Topology, l'API restituisce un elenco di nodi (risorse) e archi (relazioni) del grafico che corrispondono alla query. App Topology combina i dati di Google Cloud servizi come:

• Metadati delle risorse da Cloud Asset Inventory, App Hub e Agent Registry
• Dati di deployment, ad esempio un commit Git o la provenienza della build di un'immagine container
• Dati di sicurezza di Security Command Center, come vulnerabilità o proprietà di Identity and Access Management (IAM)
• Dati di Google Cloud Observability, come tracce e avvisi

Per eseguire una query, sono necessarie le seguenti informazioni:

• Il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati. Consulta Elenca domini per scoprire come elencare i domini disponibili.
• I nodi, gli archi e le proprietà del grafico supportati che puoi includere in una query. Puoi ottenere lo schema completo o parziale di un dominio. Per maggiori dettagli, vedi Recuperare lo schema.
• Il pattern di query con i nodi e gli archi che vuoi cercare. Consulta Eseguire query.

Prima di iniziare

1. Configura App Topology.

2. Seleziona la scheda relativa a come prevedi di utilizzare i campioni in questa pagina:

   gcloud

   Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

   REST

   Per utilizzare gli esempi di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

   Installa Google Cloud CLI.

   Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

   Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

   Per informazioni sulla configurazione dell'autenticazione per un ambiente di produzione, consulta Configura le Credenziali predefinite dell'applicazione per il codice in esecuzione su Google Cloud nella documentazione sull'autenticazione di Google Cloud .

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per utilizzare l'API App Topology, chiedi all'amministratore di concederti i seguenti ruoli IAM:

• Esegui query: App Topology Viewer (roles/apptopology.viewer) sui progetti in cui vuoi utilizzare App Topology

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per utilizzare l'API App Topology. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per utilizzare l'API App Topology sono richieste le seguenti autorizzazioni:

• Ottieni domini:
  • apptopology.domains.get
  • apptopology.domains.list
• Ottieni schemi: apptopology.schemas.get
• Recupera i dati delle risorse rilevate: apptopology.discoveredResourcesTopologies.generate
• Recupera i dati del dominio DevOps: apptopology.devOpsDomainTopologies.generate
• Recupera i dati del dominio di sicurezza: apptopology.securityDomainTopologies.generate
• Ottieni i dati del dominio SRE (tutti i dati supportati): apptopology.sreDomainTopologies.generate

Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.

Elenca domini

I domini sono insiemi di dati delle risorse incentrati su tipi specifici di query.

• Per eseguire query su tutti i dati supportati da App Topology, utilizza il dominio SRE.
• Per ottenere dati sulle risorse di agenzia, devi utilizzare il dominio SRE.
• Tutti gli esempi di risposte alle richieste in questo documento utilizzano il dominio SRE.

Se necessario, puoi elencare i domini disponibili in un progetto.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto

Esegui il comando gcloud app-topology domains list:

Linux, macOS o Cloud Shell

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

gcloud app-topology domains list --project=PROJECT_ID

Windows (PowerShell)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

gcloud app-topology domains list --project=PROJECT_ID

Windows (cmd.exe)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

gcloud app-topology domains list --project=PROJECT_ID

Dovresti ricevere una risposta simile alla seguente:

NAME
DEVOPS
SECURITY
SRE

REST

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: il tuo ID progetto

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Dovresti ricevere una risposta JSON simile alla seguente:

{
  "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"
    }
  ]
}

Ottieni lo schema

Per aiutarti a creare le query, puoi ottenere un elenco di tutti i nodi, gli archi e le proprietà supportati per un dominio. L'API REST consente anche di ottenere una parte dello schema.

Le richieste dello schema completo possono richiedere molto più tempo rispetto a quelle di uno schema parziale a causa del numero elevato di elementi nello schema.

Ottieni lo schema completo

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto
• DOMAIN: il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati.

Esegui il comando gcloud app-topology domains schema describe:

Linux, macOS o Cloud Shell

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Il seguente estratto di esempio di una risposta include solo il primo elemento dello schema per i tipi di nodi, i tipi di archi, le regole degli archi e le proprietà delle etichette.

{
  "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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: il tuo ID progetto
• DOMAIN: il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati.

Metodo HTTP e URL:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Esegui questo 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

Il seguente estratto di esempio di una risposta include solo il primo elemento nello schema per i tipi di nodi, i tipi di archi, le regole degli archi e le proprietà delle etichette.

{
  "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"
    }
  ]
}

Ottenere uno schema parziale

Puoi ottenere una parte di uno schema di dominio entro un numero specificato di hop di un'etichetta iniziale specificata.

Il comando di esempio in queste istruzioni recupera una parte dello schema a partire dal nodo Base/Agent, con una profondità di 1 e una dimensione della pagina di 5.

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: il tuo ID progetto
• DOMAIN: il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

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

Quindi esegui questo comando per inviare la richiesta 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

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

Quindi esegui questo comando per inviare la richiesta 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

In una risposta, l'ordine di nodeTypes e edgeTypes è coerente, ma l'ordine di labelProperties può variare da richiesta a richiesta.

Espandi l'intestazione Risposta per visualizzare una risposta di esempio.

Risposta

{
  "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"
}

Esegui delle query

Quando esegui una query, specifichi un pattern di query che include i nodi, gli archi e le proprietà che vuoi cercare.

I pattern di query si basano sulla sintassi di filtro AIP-160. Per una panoramica dei pattern di query e delle limitazioni delle query, consulta Informazioni sulle query. Queste istruzioni presuppongono che tu abbia letto le informazioni sulla struttura e sulle limitazioni delle query.

Le seguenti istruzioni utilizzano una query di esempio per tutti i servizi e i carichi di lavoro di App Hub nel progetto specificato, inclusi quelli registrati (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) e quelli rilevati (Base/DiscoveredService, Base/DiscoveredWorkload).

I comandi specificano il pattern di query in un file JSON. Il file è leggermente diverso per gcloud CLI e le richieste REST in queste istruzioni.

• Per gcloud CLI, specifica il dominio da interrogare come parametro del comando. Il dominio non è incluso nel file del pattern di query.
• Per le richieste REST, specifica sia il dominio sia il pattern di query nel corpo JSON della richiesta. Imposta il dominio nel campo topologyDomains e specifica il pattern di query nell'oggetto filter.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

• PROJECT_ID: il tuo ID progetto
• DOMAIN: il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati.

Salva i seguenti contenuti in un file denominato request.json:

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

Esegui il comando gcloud app-topology resources-graph generate:

Linux, macOS o Cloud Shell

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota:assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto eseguendo gcloud init; o gcloud auth login e gcloud config set project.

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

Il seguente estratto di risposta di esempio mostra i primi due nodi. Questi nodi sono server MCP. I server MCP di Google hanno l'etichetta Base/DiscoveredService, che è una delle etichette nel pattern della query.

Nell'output, le seguenti variabili rappresentano i valori associati al progetto specificato con PROJECT_ID:

• PROJECT_NUMBER: il numero di progetto per il progetto specificato.
• ORGANIZATION_NUMBER: il numero dell'organizzazione per l'organizzazione Google Cloud che contiene il progetto specificato.

{
  "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

Prima di utilizzare i dati della richiesta, apporta le sostituzioni seguenti:

• PROJECT_ID: il tuo ID progetto
• DOMAIN: il dominio per cui vuoi eseguire la query. Il dominio SRE include tutti i dati supportati.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "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"
      }
    }
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

curl (Linux, macOS o Cloud Shell)

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

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

Quindi esegui questo comando per inviare la richiesta 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)

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json. Esegui questo comando nel terminale per creare o sovrascrivere questo file nella directory corrente:

@'
{
  "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

Quindi esegui questo comando per inviare la richiesta 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

Il seguente estratto di risposta di esempio mostra i primi due nodi. Questi nodi sono server MCP. I server MCP di Google hanno l'etichetta Base/DiscoveredService, che è una delle etichette nel pattern della query.

Nell'output, le seguenti variabili rappresentano i valori associati al progetto specificato con PROJECT_ID:

• PROJECT_NUMBER: il numero di progetto per il progetto specificato.
• ORGANIZATION_NUMBER: il numero dell'organizzazione per l'organizzazione Google Cloud che contiene il progetto specificato.

{
  "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"
        }
      }
    ]
  }
}

Per altri esempi di pattern di query, vedi Pattern di query di esempio.

Pattern di query di esempio

Utilizza i seguenti esempi di pattern di query per creare i tuoi pattern di query per eseguire query. Tutti gli esempi in questa sezione utilizzano il formato JSON.

VM con gruppi di istanze, reti e dischi

Esegui query per le istanze Compute Engine in un gruppo di istanze con networking e disco.

Il pattern inizia da Base/compute.googleapis.com/Instance e ha tre rami edge principali sotto l'oggetto neighbors di livello superiore che definiscono questi criteri:

• Istanze che appartengono a un gruppo di istanze gestite
• Istanze con una rete connessa
• Istanze con Persistent Disk

Poiché i rami vengono combinati con AND, la risposta include solo le istanze che appartengono a un gruppo di istanze gestite e hanno sia una rete che un 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"
          }
        }
      }
    }
  ]
}

Risorse agentiche

Esegui query per risorse agentiche e le loro relazioni utilizzando le informazioni di Agent Registry, inclusi i dati per agenti, server MCP, endpoint e skill.

{
  "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"
    }
  }
}

App Topology supporta due tipi di endpoint:

• Base/aiplatform.googleapis.com/Endpoint è un endpoint del modello di Gemini Enterprise Agent Platform.
• Base/Endpoint è l'URL di destinazione di un Agent Endpoint ed è un'etichetta su un servizio di Agent Registry (Base/agentregistry.googleapis.com/Service). Poiché Base/agentregistry.googleapis.com/Service è incluso nel pattern di query, gli Agent Endpoint sono inclusi nei risultati della risposta alla query.

Traffico dell'agente

Esegui query per il traffico tra agenti e altri agenti o server MCP utilizzando i dati di Cloud Trace. Ogni perimetro include dati sulla percentuale di errori e sulla latenza 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"
          }
        }
      }
    }
  ]
}

Passaggi successivi

• Scopri di più sull'utilizzo del server MCP remoto.
• Scopri come eseguire query in Cloud Hub.
• Scopri di più sull'esecuzione di query in Gemini Enterprise Agent Platform.