Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Utiliser l'API App Topology

Vous pouvez exécuter des requêtes de manière programmatique pour corréler des données dans Google Cloud à l'aide de l'API REST ou de Google Cloud CLI.

Présentation

Lorsque vous exécutez une requête API App Topology, l'API renvoie une liste de nœuds (ressources) et d'arêtes (relations) de graphique correspondant à votre requête. App Topology combine les données de différents services Google Cloud , tels que :

Métadonnées de ressources provenant de l'inventaire des éléments cloud, d'App Hub et du registre d'agents
Données de déploiement, telles qu'un commit Git ou la provenance de compilation d'une image de conteneur
Données de sécurité provenant de Security Command Center, telles que les failles ou la propriété du Identity and Access Management (IAM)
Données Google Cloud Observability, telles que les traces et les alertes

Pour exécuter une requête, vous avez besoin des informations suivantes :

Domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles. Consultez list domains pour savoir comment lister les domaines disponibles.
Nœuds, arêtes et propriétés de graphiques compatibles que vous pouvez inclure dans une requête. Vous pouvez obtenir le schéma complet ou partiel d'un domaine. Pour en savoir plus, consultez Obtenir le schéma.
Le schéma de requête avec les nœuds et les arêtes que vous souhaitez rechercher. Consultez Exécuter des requêtes.

Avant de commencer

Configurez App Topology.
Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :
gcloud

Dans la console Google Cloud , activez Cloud Shell.

Activer Cloud Shell

En bas de la console Google Cloud , une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.
REST

Pour utiliser les exemples API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à la gcloud CLI.
Pour en savoir plus, consultez la section S'authentifier pour utiliser REST dans la documentation sur l'authentification Google Cloud .
Pour en savoir plus sur la configuration de l'authentification dans un environnement de production, consultez Configurer les Identifiants par défaut de l'application pour le code s'exécutant sur Google Cloud dans la documentation sur l'authentification Google Cloud .

Rôles requis

Pour obtenir les autorisations nécessaires pour utiliser l'API App Topology, demandez à votre administrateur de vous accorder les rôles IAM suivants :

Exécuter des requêtes : Lecteur App Topology (roles/apptopology.viewer) sur les projets dans lesquels vous souhaitez utiliser App Topology

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Ces rôles prédéfinis contiennent les autorisations requises pour utiliser l'API App Topology. Pour connaître les autorisations exactes requises, développez la section Autorisations requises :

Autorisations requises

Les autorisations suivantes sont requises pour utiliser l'API App Topology :

Obtenir des domaines :
- apptopology.domains.get
- apptopology.domains.list
Obtenir les schémas : apptopology.schemas.get
Obtenez les données de la ressource détectée : apptopology.discoveredResourcesTopologies.generate
Obtenez des données sur le domaine DevOps : apptopology.devOpsDomainTopologies.generate
Obtenez les données du domaine de sécurité : apptopology.securityDomainTopologies.generate
Obtenez les données du domaine SRE (toutes les données acceptées) : apptopology.sreDomainTopologies.generate

Vous pouvez également obtenir ces autorisations avec des rôles personnalisés ou d'autres rôles prédéfinis.

Lister les domaines

Les domaines sont des ensembles de données de ressources axés sur des types de requêtes spécifiques.

Pour interroger toutes les données compatibles avec App Topology, utilisez le domaine SRE.
Pour obtenir des données sur les ressources agentiques, vous devez utiliser le domaine SRE.
Tous les exemples de réponses aux requêtes de ce document utilisent le domaine SRE.

Si nécessaire, vous pouvez lister les domaines disponibles dans un projet.

gcloud

Lister les domaines

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID du projet

Exécutez la commande 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

Vous devriez obtenir un résultat semblable à celui-ci :

NAME
DEVOPS
SECURITY
SRE

REST

Lister les domaines

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PROJECT_ID : ID du projet

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Remarque : La commande suivante suppose que vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

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)

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Obtenir le schéma

Pour vous aider à créer vos requêtes, vous pouvez obtenir la liste de tous les nœuds, arêtes et propriétés compatibles pour un domaine. L'API REST vous permet également d'obtenir une partie du schéma.

Les requêtes pour le schéma complet peuvent prendre beaucoup plus de temps que celles pour un schéma partiel en raison du grand nombre d'éléments dans le schéma.

Obtenir le schéma complet

gcloud

Obtenir le schéma complet

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID du projet
DOMAIN : domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles.

Exécutez la commande 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

L'extrait d'exemple suivant d'une réponse n'inclut que le premier élément du schéma pour les types de nœuds, les types d'arêtes, les règles d'arêtes et les propriétés de libellé.

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

Obtenir le schéma complet

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PROJECT_ID : ID du projet
DOMAIN : domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles.

Méthode HTTP et URL :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Exécutez la commande suivante :

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)

Exécutez la commande suivante :

$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

L'extrait d'exemple suivant d'une réponse n'inclut que le premier élément du schéma pour les types de nœuds, les types d'arêtes, les règles d'arêtes et les propriétés de libellé.

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

Obtenir un schéma partiel

Vous pouvez obtenir une partie d'un schéma de domaine dans un nombre de sauts spécifié à partir d'un libellé de départ spécifié.

L'exemple de commande de ces instructions récupère une partie du schéma en commençant au nœud Base/Agent, avec une profondeur de 1 et une taille de page de 5.

Obtenir un schéma partiel

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PROJECT_ID : ID du projet
DOMAIN : domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

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

Exécutez ensuite la commande suivante pour envoyer votre requête 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)

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

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

Exécutez ensuite la commande suivante pour envoyer votre requête 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

Dans une réponse, l'ordre de nodeTypes et de edgeTypes est cohérent, mais l'ordre de labelProperties peut varier d'une requête à l'autre.

Développez l'en-tête Réponse pour afficher un exemple de réponse.

Réponse

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

Exécuter des requêtes

Lorsque vous exécutez une requête, vous spécifiez un modèle de requête qui inclut les nœuds, les arêtes et les propriétés que vous souhaitez rechercher.

Les schémas de requête sont basés sur la syntaxe de filtrage AIP-160. Pour obtenir une présentation des modèles et des limites de requêtes, consultez À propos des requêtes. Ces instructions supposent que vous avez lu les informations sur la structure et les limites des requêtes.

Les instructions suivantes utilisent un exemple de requête pour tous les services et charges de travail App Hub du projet spécifié, y compris ceux qui sont enregistrés (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) et ceux qui sont découverts (Base/DiscoveredService, Base/DiscoveredWorkload).

Les commandes spécifient le modèle de requête dans un fichier JSON. Le fichier est légèrement différent pour les requêtes gcloud CLI et REST dans ces instructions.

Pour gcloud CLI, spécifiez le domaine à interroger en tant que paramètre de la commande. Le domaine n'est pas inclus dans le fichier de schéma de requête.
Pour les requêtes REST, spécifiez à la fois le domaine et le schéma de requête dans le corps JSON de la requête. Définissez le domaine dans le champ topologyDomains et spécifiez le modèle de requête sous l'objet filter.

gcloud

Générer une topologie

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

PROJECT_ID : ID du projet
DOMAIN : domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles.

Enregistrez le code suivant dans un fichier nommé request.json :

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

Exécutez la commande 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

L'extrait de réponse suivant montre les deux premiers nœuds. Ces nœuds sont des serveurs MCP. Les serveurs MCP Google ont le libellé Base/DiscoveredService, qui est l'un des libellés du modèle de requête.

Dans le résultat, les variables suivantes représentent les valeurs associées au projet que vous avez spécifié avec PROJECT_ID :

PROJECT_NUMBER : numéro du projet spécifié.
ORGANIZATION_NUMBER : numéro de l'organisation Google Cloud contenant le projet spécifié.

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

Générer une topologie

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

PROJECT_ID : ID du projet
DOMAIN : domaine que vous souhaitez interroger. Le domaine SRE inclut toutes les données compatibles.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, développez l'une des options suivantes :

curl (Linux, macOS ou Cloud Shell)

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

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

Exécutez ensuite la commande suivante pour envoyer votre requête 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)

Enregistrez le corps de la requête dans un fichier nommé request.json. Exécutez la commande suivante dans le terminal pour créer ou écraser ce fichier dans le répertoire actuel :

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

Exécutez ensuite la commande suivante pour envoyer votre requête 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

Dans le résultat, les variables suivantes représentent les valeurs associées au projet que vous avez spécifié avec PROJECT_ID :

PROJECT_NUMBER : numéro du projet spécifié.
ORGANIZATION_NUMBER : numéro de l'organisation Google Cloud contenant le projet spécifié.

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

Pour d'autres exemples de schémas de requête, consultez Exemples de schémas de requête.

Exemples de formats de requête

Utilisez les exemples de modèles de requête suivants pour vous aider à créer vos propres modèles de requête pour exécuter des requêtes. Tous les exemples de cette section utilisent le format JSON.

VM avec groupes d'instances, réseaux et disques

Interrogez les instances Compute Engine d'un groupe d'instances avec mise en réseau et disque.

Le modèle commence à Base/compute.googleapis.com/Instance et comporte trois branches edge principales sous l'objet neighbors de premier niveau qui définissent ces critères :

Instances appartenant à un groupe d'instances géré
Instances avec un réseau connecté
Instances avec Persistent Disk

Comme les branches sont combinées avec AND, la réponse n'inclut que les instances qui appartiennent à un groupe d'instances géré et qui disposent à la fois d'un réseau et d'un disque.

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

Ressources agentiques

Interrogez les ressources agentiques et leurs relations à l'aide des informations du registre d'agents, y compris les données pour les agents, les serveurs MCP, les points de terminaison et les compétences.

{
  "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 prend en charge deux types de points de terminaison :

Base/aiplatform.googleapis.com/Endpoint est un point de terminaison de modèle Gemini Enterprise Agent Platform.
Base/Endpoint est l'URL cible d'un agent. Il s'agit d'un libellé sur un service Agent Registry (Base/agentregistry.googleapis.com/Service). Étant donné que Base/agentregistry.googleapis.com/Service est inclus dans le modèle de requête, les points de terminaison de l'agent sont inclus dans les résultats de la réponse à la requête.

Trafic de l'agent

Interrogez le trafic entre les agents et d'autres agents ou serveurs MCP à l'aide des données de Cloud Trace. Chaque périphérie inclut des données sur le taux d'erreur et la latence 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"
          }
        }
      }
    }
  ]
}

Étapes suivantes

Découvrez comment utiliser le serveur MCP à distance.
Découvrez comment exécuter des requêtes dans Cloud Hub.
Découvrez comment exécuter des requêtes dans Gemini Enterprise Agent Platform.

Utiliser l'API App Topology Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Présentation

Avant de commencer

gcloud

REST

Rôles requis

Autorisations requises

Lister les domaines

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Obtenir le schéma

Obtenir le schéma complet

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Obtenir un schéma partiel

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Réponse

Exécuter des requêtes

gcloud

Linux, macOS ou Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS ou Cloud Shell)

PowerShell (Windows)

Exemples de formats de requête

VM avec groupes d'instances, réseaux et disques

Ressources agentiques

Trafic de l'agent

Étapes suivantes

Utiliser l'API App Topology