Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Usa la API de App Topology

Puedes ejecutar consultas de forma programática para correlacionar datos en Google Cloud con la API de REST o Google Cloud CLI.

Descripción general

Cuando ejecutas una consulta a la API de App Topology, esta devuelve una lista de nodos (recursos) y aristas (relaciones) del grafo que coinciden con tu consulta. App Topology combina datos de varios Google Cloud servicios, como los siguientes:

Metadatos de recursos de Cloud Asset Inventory, App Hub y Agent Registry
Datos de Deployment, como la confirmación de Git o la procedencia de compilación de una imagen de contenedor
Datos de seguridad de Security Command Center, como vulnerabilidades o propiedad de Identity and Access Management (IAM)
Datos de Google Cloud Observability, como seguimientos y alertas

Para ejecutar una consulta, necesitas la siguiente información:

Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos. Consulta list domains para obtener información sobre cómo mostrar los dominios disponibles.
Los nodos, las aristas y las propiedades del gráfico admitidos que puedes incluir en una consulta. Puedes obtener el esquema completo o parcial de un dominio. Para obtener más información, consulta Cómo obtener el esquema.
Es el patrón de consulta con los nodos y los bordes que deseas buscar. Consulta Ejecuta consultas.

Antes de comenzar

Configura la topología de la app.
Selecciona la pestaña que corresponda a la forma en que planeas usar las muestras de esta página:
gcloud

En la consola de Google Cloud , activa Cloud Shell.

Activa Cloud Shell

En la parte inferior de la consola de Google Cloud , se inicia una sesión de Cloud Shell en la que se muestra una ventana de línea de comandos. Cloud Shell es un entorno de shell con Google Cloud CLI ya instalada y con valores ya establecidos para el proyecto actual. La sesión puede tardar unos segundos en inicializarse.
REST

Para usar las muestras de la API de REST incluidas en esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la gcloud CLI.
Para obtener más información, consulta Autentícate para usar REST en la documentación de autenticación de Google Cloud .
Para obtener información sobre cómo configurar la autenticación para un entorno de producción, consulta Configura las credenciales predeterminadas de la aplicación para el código que se ejecuta en Google Cloud en la documentación de autenticación de Google Cloud .

Roles obligatorios

Para obtener los permisos que necesitas para usar la API de App Topology, pídele a tu administrador que te otorgue los siguientes roles de IAM:

Ejecutar consultas: Visualizador de App Topology (roles/apptopology.viewer) en los proyectos en los que deseas usar App Topology

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Estos roles predefinidos contienen los permisos necesarios para usar la API de App Topology. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para usar la API de App Topology:

Obtener dominios:
- apptopology.domains.get
- apptopology.domains.list
Obtener esquemas: apptopology.schemas.get
Obtén datos de recursos descubiertos: apptopology.discoveredResourcesTopologies.generate
Obtén datos del dominio de DevOps: apptopology.devOpsDomainTopologies.generate
Obtén datos del dominio de seguridad: apptopology.securityDomainTopologies.generate
Obtén datos del dominio de SRE (todos los datos admitidos): apptopology.sreDomainTopologies.generate

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Lista de dominios

Los dominios son conjuntos de datos de recursos que se enfocan en tipos específicos de búsquedas.

Para consultar todos los datos que admite la Topología de la app, usa el dominio SRE.
Para obtener datos sobre los recursos de agentes, debes usar el dominio SRE.
En todos los ejemplos de respuestas a solicitudes de este documento, se usa el dominio SRE.

Si es necesario, puedes enumerar los dominios que están disponibles en un proyecto.

gcloud

Lista de dominios

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.

Ejecuta el comando gcloud app-topology domains list:

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

Deberías recibir una respuesta similar a la que figura a continuación:

NAME
DEVOPS
SECURITY
SRE

REST

Lista de dominios

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Nota: Con el siguiente comando, se supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login , o a través del uso de Cloud Shell, que accede de forma automática a gcloud CLI . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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: El siguiente comando supone que accediste a gcloud CLI con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login . Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Ejecuta el siguiente 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

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

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

Obtén el esquema

Para ayudarte a crear tus consultas, puedes obtener una lista de todos los nodos, las aristas y las propiedades admitidos para un dominio. La API de REST también te permite obtener una parte del esquema.

Las solicitudes del esquema completo pueden tardar mucho más que las solicitudes de un esquema parcial debido a la gran cantidad de elementos que contiene el esquema.

Obtén el esquema completo

gcloud

Obtener el esquema completo

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.
DOMAIN: Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos.

Ejecuta el comando gcloud app-topology domains schema describe:

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

El siguiente fragmento de ejemplo de una respuesta solo incluye el primer elemento del esquema para los tipos de nodos, los tipos de bordes, las reglas de bordes y las propiedades de etiquetas.

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

Obtener el esquema completo

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.
DOMAIN: Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos.

Método HTTP y URL:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Ejecuta el siguiente 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)

Ejecuta el siguiente 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

El siguiente ejemplo de un extracto de respuesta solo incluye el primer elemento del esquema para los tipos de nodos, los tipos de aristas, las reglas de aristas y las propiedades de etiquetas.

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

Obtén un esquema parcial

Puedes obtener una parte del esquema de un dominio dentro de una cantidad especificada de saltos de una etiqueta inicial especificada.

El comando de ejemplo de estas instrucciones obtiene una parte del esquema a partir del nodo Base/Agent, con una profundidad de 1 y un tamaño de página de 5.

Obtener esquema parcial

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.
DOMAIN: Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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)

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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

En una respuesta, el orden de nodeTypes y edgeTypes es coherente, pero el orden de labelProperties puede variar de una solicitud a otra.

Expande el encabezado Response para ver un ejemplo de respuesta.

Respuesta

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

Ejecuta consultas

Cuando ejecutas una consulta, especificas un patrón de consulta que incluye los nodos, los bordes y las propiedades que deseas buscar.

Los patrones de consulta se basan en la sintaxis de filtrado del AIP-160. Para obtener una descripción general de los patrones de consulta y las limitaciones de las consultas, consulta Acerca de las consultas. En estas instrucciones, se supone que leíste la información sobre la estructura y las limitaciones de las consultas.

En las siguientes instrucciones, se usa una consulta de ejemplo para todos los servicios y cargas de trabajo de App Hub en el proyecto especificado, incluidos los que están registrados (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) y los que se descubrieron (Base/DiscoveredService, Base/DiscoveredWorkload).

Los comandos especifican el patrón de consulta en un archivo JSON. El archivo es ligeramente diferente para las solicitudes de gcloud CLI y de REST en estas instrucciones.

En gcloud CLI, especifica el dominio para consultar como un parámetro del comando. El dominio no se incluye en el archivo de patrones de consulta.
En el caso de las solicitudes de REST, especifica el dominio y el patrón de consulta en el cuerpo JSON de la solicitud. Establece el dominio en el campo topologyDomains y especifica el patrón de consulta en el objeto filter.

gcloud

Genera la topología

Antes de usar cualquiera de los datos de comando a continuación, haz los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.
DOMAIN: Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos.

Guarda el siguiente código en un archivo llamado request.json.

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

Ejecuta el comando gcloud app-topology resources-graph generate:

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

El siguiente fragmento de respuesta de ejemplo muestra los primeros 2 nodos. Estos nodos son servidores de MCP. Los servidores de MCP de Google tienen la etiqueta Base/DiscoveredService, que es una de las etiquetas del patrón de consulta.

En el resultado, las siguientes variables representan valores asociados con el proyecto que especificaste con PROJECT_ID:

PROJECT_NUMBER: Es el número del proyecto especificado.
ORGANIZATION_NUMBER: Es el número de la organización Google Cloud que contiene el proyecto especificado.

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

REST

Genera la topología

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_ID: Es el ID del proyecto.
DOMAIN: Es el dominio que deseas consultar. El dominio SRE incluye todos los datos admitidos.

Método HTTP y URL:

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

Cuerpo JSON de la solicitud:

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

Para enviar tu solicitud, expande una de estas opciones:

curl (Linux, macOS o Cloud Shell)

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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)

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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

En el resultado, las siguientes variables representan valores asociados con el proyecto que especificaste con PROJECT_ID:

PROJECT_NUMBER: Es el número del proyecto especificado.
ORGANIZATION_NUMBER: Es el número de la organización Google Cloud que contiene el proyecto especificado.

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

Para ver más ejemplos de patrones de consulta, consulta Ejemplos de patrones de consulta.

Patrones de consultas de ejemplo

Usa los siguientes ejemplos de patrones de consultas para crear tus propios patrones de consultas para ejecutar consultas. Todos los ejemplos de esta sección usan el formato JSON.

VMs con grupos de instancias, redes y discos

Consulta las instancias de Compute Engine en un grupo de instancias con redes y discos.

El patrón comienza en Base/compute.googleapis.com/Instance y tiene tres ramas edge principales en el objeto neighbors de nivel superior que definen estos criterios:

Instancias que pertenecen a un grupo de instancias administrado
Instancias con una red conectada
Instancias con Persistent Disk

Debido a que las ramas se combinan con AND, la respuesta solo incluye instancias que pertenecen a un grupo de instancias administrado y tienen tanto una red como 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"
          }
        }
      }
    }
  ]
}

Recursos de agente

Consultar recursos de agentes y sus relaciones con información de Agent Registry, incluidos datos de agentes, servidores de MCP, endpoints y habilidades

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

App Topology admite dos tipos de extremos:

Base/aiplatform.googleapis.com/Endpoint es un extremo del modelo de Gemini Enterprise Agent Platform.
Base/Endpoint es la URL de destino de un agente y es una etiqueta en un servicio de registro de agentes (Base/agentregistry.googleapis.com/Service). Como Base/agentregistry.googleapis.com/Service se incluye en el patrón de búsqueda, los extremos del agente se incluyen en los resultados de la respuesta de la búsqueda.

Tráfico de agentes

Consulta el tráfico entre agentes y otros agentes o servidores de MCP con datos de Cloud Trace. Cada arista incluye datos de la tasa de error y la latencia del percentil 95.

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

¿Qué sigue?

Obtén más información para usar el servidor de MCP remoto.
Obtén más información para ejecutar consultas en Cloud Hub.
Obtén más información para ejecutar consultas en Gemini Enterprise Agent Platform.

Usa la API de App Topology Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Descripción general

Antes de comenzar

gcloud

REST

Roles obligatorios

Permisos necesarios

Lista de dominios

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Obtén el esquema

Obtén el esquema completo

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Obtén un esquema parcial

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Respuesta

Ejecuta consultas

gcloud

Linux, macOS o Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS o Cloud Shell)

PowerShell (Windows)

Patrones de consultas de ejemplo

VMs con grupos de instancias, redes y discos

Recursos de agente

Tráfico de agentes

¿Qué sigue?

Usa la API de App Topology