Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

App Topology API verwenden

Sie können programmatisch Abfragen ausführen, um Daten in Google Cloud mithilfe der REST API oder der Google Cloud CLI zu korrelieren.

Übersicht

Wenn Sie eine App Topology API-Abfrage ausführen, gibt die API eine Liste von Knoten (Ressourcen) und Kanten (Beziehungen) zurück, die Ihrer Abfrage entsprechen. Bei der Anwendungstopologie werden Daten aus verschiedenen Google Cloud Diensten kombiniert, z. B.:

Ressourcenmetadaten aus Cloud Asset Inventory, App Hub und Agent Registry
Bereitstellungsdaten, z. B. ein Git-Commit oder die Build-Herkunft eines Container-Images
Sicherheitsdaten aus Security Command Center, z. B. Sicherheitslücken oder Inhaberschaft der Identitäts- und Zugriffsverwaltung (Identity and Access Management, IAM)
Google Cloud Observability-Daten wie Traces und Benachrichtigungen

Zum Ausführen einer Abfrage benötigen Sie die folgenden Informationen:

Die Domain, die Sie abfragen möchten. Die Domain SRE umfasst alle unterstützten Daten. Informationen zum Auflisten verfügbarer Domains finden Sie unter Domains auflisten.
Die unterstützten Knoten, Kanten und Attribute, die Sie in eine Abfrage einfügen können. Sie können das vollständige oder teilweise Schema für eine Domain abrufen. Weitere Informationen finden Sie unter Schema abrufen.
Das Abfragemuster mit den Knoten und Kanten, nach denen Sie suchen möchten. Weitere Informationen finden Sie unter Abfragen ausführen.

Hinweis

Anwendungstopologie einrichten
Wählen Sie den Tab für die geplante Verwendung der Beispiele auf dieser Seite aus:
gcloud

Aktivieren Sie Cloud Shell in der Google Cloud Console.

Cloud Shell aktivieren

Unten in der Google Cloud Console wird eine Cloud Shell-Sitzung gestartet und eine Eingabeaufforderung angezeigt. Cloud Shell ist eine Shell-Umgebung, in der das Google Cloud CLI bereits installiert ist und Werte für Ihr aktuelles Projekt bereits festgelegt sind. Das Initialisieren der Sitzung kann einige Sekunden dauern.
REST

Wenn Sie die REST API-Beispiele auf dieser Seite in einer lokalen Entwicklungsumgebung verwenden möchten, verwenden Sie die Anmeldedaten, die Sie der gcloud CLI bereitstellen.
Weitere Informationen finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Für die Verwendung von REST authentifizieren.
Informationen zum Einrichten der Authentifizierung für eine Produktionsumgebung finden Sie in der Dokumentation zur Google Cloud -Authentifizierung unter Standardanmeldedaten für Anwendungen für Code einrichten, der auf Google Cloudausgeführt wird .

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwendung der App Topology API benötigen:

Abfragen ausführen: App Topology Viewer (roles/apptopology.viewer) für die Projekte, in denen Sie die Anwendungstopologie verwenden möchten

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die für die Verwendung der App Topology API erforderlich sind. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um die App Topology API zu verwenden:

Domains abrufen:
- apptopology.domains.get
- apptopology.domains.list
Schemas abrufen: apptopology.schemas.get
Daten der erkannten Ressource abrufen: apptopology.discoveredResourcesTopologies.generate
DevOps-Domänendaten abrufen: apptopology.devOpsDomainTopologies.generate
Daten zur Sicherheitsdomain abrufen: apptopology.securityDomainTopologies.generate
SRE-Domänendaten abrufen (alle unterstützten Daten): apptopology.sreDomainTopologies.generate

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Domains auflisten

Domains sind Gruppen von Ressourcendaten, die sich auf bestimmte Arten von Anfragen konzentrieren.

Wenn Sie alle von der Anwendungstopologie unterstützten Daten abfragen möchten, verwenden Sie die Domain SRE.
Wenn Sie Daten zu agentischen Ressourcen abrufen möchten, müssen Sie die Domain SRE verwenden.
In allen Beispielen für Anforderungsantworten in diesem Dokument wird die Domain SRE verwendet.

Bei Bedarf können Sie Domains auflisten, die in einem Projekt verfügbar sind.

gcloud

Domains auflisten

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

PROJECT_ID: Ihre Projekt-ID

Führen Sie den Befehl gcloud app-topology domains list aus:

Linux, macOS oder 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

Sie sollten eine Antwort ähnlich der folgenden erhalten:

NAME
DEVOPS
SECURITY
SRE

REST

Domains auflisten

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Projekt-ID

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt oder die Cloud Shell genutzt haben, die Sie automatisch in der gcloud-Befehlszeile anmeldet. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie folgenden Befehl aus:

$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

Sie sollten eine JSON-Antwort ähnlich wie diese erhalten:

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

Schema abrufen

Um Ihnen das Erstellen von Abfragen zu erleichtern, können Sie eine Liste aller unterstützten Knoten, Kanten und Eigenschaften für eine Domain abrufen. Mit der REST API können Sie auch einen Teil des Schemas abrufen.

Anfragen für das vollständige Schema können aufgrund der großen Anzahl von Elementen im Schema deutlich länger dauern als Anfragen für ein Teilschema.

Vollständiges Schema abrufen

gcloud

Vollständiges Schema abrufen

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

PROJECT_ID: Ihre Projekt-ID
DOMAIN: Die Domain, die Sie abfragen möchten. Die SRE-Domain umfasst alle unterstützten Daten.

Führen Sie den Befehl gcloud app-topology domains schema describe aus:

Linux, macOS oder 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

Das folgende Beispiel aus einer Antwort enthält nur das erste Element im Schema für Knotentypen, Kantentypen, Kantenregeln und Label-Eigenschaften.

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

Vollständiges Schema abrufen

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Projekt-ID
DOMAIN: Die Domain, die Sie abfragen möchten. Die SRE-Domain umfasst alle unterstützten Daten.

HTTP-Methode und URL:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Führen Sie folgenden Befehl aus:

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Führen Sie diesen Befehl aus:

$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

Das folgende Beispiel aus einer Antwort enthält nur das erste Element im Schema für Knotentypen, Kantentypen, Kantenregeln und Label-Eigenschaften.

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

Teilschema abrufen

Sie können einen Teil eines Domainschemas innerhalb einer bestimmten Anzahl von Schritten eines angegebenen Startlabels abrufen.

Mit dem Beispielbefehl in dieser Anleitung wird ein Teil des Schemas ab dem Knoten Base/Agent mit einer Tiefe von 1 und einer Seitengröße von 5 abgerufen.

Teilschema abrufen

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Projekt-ID
DOMAIN: Die Domain, die Sie abfragen möchten. Die SRE-Domain umfasst alle unterstützten Daten.

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben:

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden:

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben:

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden:

$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 einer Antwort ist die Reihenfolge von nodeTypes und edgeTypes konsistent, die Reihenfolge von labelProperties kann jedoch von Anfrage zu Anfrage variieren.

Maximieren Sie die Überschrift Antwort, um eine Beispielantwort zu sehen.

Antwort

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

Abfragen ausführen

Wenn Sie eine Abfrage ausführen, geben Sie ein Abfragemuster an, das die Knoten, Kanten und Eigenschaften enthält, nach denen Sie suchen möchten.

Abfragemuster basieren auf der AIP-160-Filtersyntax. Eine Übersicht über Abfragemuster und ‑beschränkungen finden Sie unter Abfragen. Bei dieser Anleitung wird davon ausgegangen, dass Sie die Informationen zur Abfragestruktur und zu Einschränkungen gelesen haben.

In der folgenden Anleitung wird eine Beispielabfrage für alle App Hub-Dienste und ‑Arbeitslasten im angegebenen Projekt verwendet, einschließlich der registrierten (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) und der erkannten (Base/DiscoveredService, Base/DiscoveredWorkload).

Mit den Befehlen wird das Abfragemuster in einer JSON-Datei angegeben. Die Datei unterscheidet sich in dieser Anleitung geringfügig für gcloud CLI- und REST-Anfragen.

Geben Sie für die gcloud CLI die abzufragende Domain als Parameter des Befehls an. Die Domain ist nicht in der Datei mit Abfragemustern enthalten.
Geben Sie für REST-Anfragen sowohl die Domain als auch das Abfragemuster im JSON-Text der Anfrage an. Legen Sie die Domain im Feld topologyDomains fest und geben Sie das Abfragemuster unter dem filter-Objekt an.

gcloud

Topologie generieren

Ersetzen Sie folgende Werte, bevor sie einen der Befehlsdaten verwenden:

PROJECT_ID: Ihre Projekt-ID
DOMAIN: Die Domain, die Sie abfragen möchten. Die SRE-Domain umfasst alle unterstützten Daten.

Speichern Sie den folgenden Inhalt in einer Datei mit dem Namen request.json:

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

Führen Sie den Befehl gcloud app-topology resources-graph generate aus:

Linux, macOS oder 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

Der folgende Auszug aus einer Beispielantwort zeigt die ersten beiden Knoten. Diese Knoten sind MCP-Server. Google-MCP-Server haben das Label Base/DiscoveredService, das eines der Labels im Abfragemuster ist.

In der Ausgabe stehen die folgenden Variablen für Werte, die dem Projekt zugeordnet sind, das Sie mit PROJECT_ID angegeben haben:

PROJECT_NUMBER: Die Projektnummer für das angegebene Projekt.
ORGANIZATION_NUMBER: Die Organisationsnummer für die Google Cloud Organisation, die das angegebene Projekt enthält.

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

Topologie generieren

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

PROJECT_ID: Ihre Projekt-ID
DOMAIN: Die Domain, die Sie abfragen möchten. Die SRE-Domain umfasst alle unterstützten Daten.

HTTP-Methode und URL:

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

JSON-Text anfordern:

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

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

curl (Linux, macOS oder Cloud Shell)

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben:

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden:

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)

Hinweis: Der folgende Befehl setzt voraus, dass Sie sich mit Ihrem Nutzerkonto in der gcloud-Befehlszeile angemeldet haben, indem Sie gcloud init oder gcloud auth login ausgeführt haben. Um herauszufinden, welches Konto gerade aktiv ist, führen Sie gcloud auth list aus.

Speichern Sie den Anfragetext in einer Datei mit dem Namen request.json. Führen Sie folgenden Befehl im Terminal aus, um diese Datei im aktuellen Verzeichnis zu erstellen oder zu überschreiben:

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

Führen Sie dann folgenden Befehl aus, um Ihre REST-Anfrage zu senden:

$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

In der Ausgabe stehen die folgenden Variablen für Werte, die dem Projekt zugeordnet sind, das Sie mit PROJECT_ID angegeben haben:

PROJECT_NUMBER: Die Projektnummer für das angegebene Projekt.
ORGANIZATION_NUMBER: Die Organisationsnummer für die Google Cloud Organisation, die das angegebene Projekt enthält.

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

Weitere Beispiele für Abfragemuster finden Sie unter Beispiele für Abfragemuster.

Beispielmuster für Abfragen

Die folgenden Beispiele für Abfragemuster können Ihnen dabei helfen, eigene Abfragemuster zum Ausführen von Abfragen zu erstellen. In allen Beispielen in diesem Abschnitt wird das JSON-Format verwendet.

VMs mit Instanzgruppen, Netzwerken und Laufwerken

Abfrage für Compute Engine-Instanzen in einer Instanzgruppe mit Netzwerk und Laufwerk.

Das Muster beginnt bei Base/compute.googleapis.com/Instance und hat drei primäre edge-Zweige unter dem übergeordneten neighbors-Objekt, die diese Kriterien definieren:

Instanzen, die zu einer verwalteten Instanzgruppe gehören
Instanzen mit einem verbundenen Netzwerk
Instanzen mit Persistent Disk

Da Zweige mit AND kombiniert werden, enthält die Antwort nur Instanzen, die zu einer verwalteten Instanzgruppe gehören und sowohl ein Netzwerk als auch ein Laufwerk haben.

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

Agentische Ressourcen

Agentenressourcen und ihre Beziehungen mit Informationen aus der Agent Registry abfragen, einschließlich Daten für Agenten, MCP-Server, Endpunkte und Skills.

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

Die Anwendungstopologie unterstützt zwei Arten von Endpunkten:

Base/aiplatform.googleapis.com/Endpoint ist ein Modellendpunkt der Gemini Enterprise Agent Platform.
Base/Endpoint ist die Ziel-URL für einen Agenten und ein Label für einen Agent Registry-Dienst (Base/agentregistry.googleapis.com/Service). Da Base/agentregistry.googleapis.com/Service im Abfragemuster enthalten ist, sind Agentenendpunkte in den Ergebnissen der Abfrageantwort enthalten.

KI-Agenten-Traffic

Mit Daten aus Cloud Trace können Sie Traffic zwischen Agenten und anderen Agenten oder MCP-Servern abfragen. Jeder Edge enthält Daten zur Fehlerrate und zur P95-Latenz.

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

App Topology API verwenden Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Übersicht

Hinweis

gcloud

REST

Erforderliche Rollen

Erforderliche Berechtigungen

Domains auflisten

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Schema abrufen

Vollständiges Schema abrufen

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Teilschema abrufen

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Antwort

Abfragen ausführen

gcloud

Linux, macOS oder Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS oder Cloud Shell)

PowerShell (Windows)

Beispielmuster für Abfragen

VMs mit Instanzgruppen, Netzwerken und Laufwerken

Agentische Ressourcen

KI-Agenten-Traffic

Nächste Schritte

App Topology API verwenden