Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Menggunakan App Topology API

Anda dapat menjalankan kueri secara terprogram untuk mengorelasikan data di seluruh Google Cloud dengan menggunakan REST API atau Google Cloud CLI.

Ringkasan

Saat Anda menjalankan kueri App Topology API, API akan menampilkan daftar node grafik (resource) dan tepi (hubungan) yang cocok dengan kueri Anda. App Topology menggabungkan data di berbagai Google Cloud layanan seperti:

Metadata resource dari Inventaris Aset Cloud, App Hub, Agent Registry
Data deployment, seperti commit Git atau provenance build image container
Data keamanan dari Security Command Center seperti kerentanan atau kepemilikan Identity and Access Management (IAM)
Data Google Cloud Observability seperti rekaman aktivitas dan pemberitahuan

Untuk menjalankan kueri, Anda memerlukan informasi berikut:

Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung. Lihat mencantumkan domain untuk mempelajari cara mencantumkan domain yang tersedia.
Node, tepi, dan properti grafik yang didukung yang dapat Anda sertakan dalam kueri. Anda bisa mendapatkan skema penuh atau sebagian untuk domain. Untuk mengetahui detailnya, lihat Mendapatkan skema.
Pola kueri dengan node dan tepi yang ingin Anda telusuri. Lihat Menjalankan kueri.

Sebelum memulai

Siapkan Topologi Aplikasi.
Pilih tab untuk melihat bagaimana Anda berencana menggunakan contoh di halaman ini:
gcloud

Di konsol Google Cloud , aktifkan Cloud Shell.

Aktifkan Cloud Shell

Di bagian bawah konsol Google Cloud , sesi Cloud Shell akan dimulai dan menampilkan perintah command line. Cloud Shell adalah lingkungan shell dengan Google Cloud CLI yang sudah terinstal, dan dengan nilai yang sudah ditetapkan untuk project Anda saat ini. Diperlukan waktu beberapa detik untuk melakukan inisialisasi pada sesi.
REST

Untuk menggunakan contoh REST API di halaman ini dalam lingkungan pengembangan lokal, gunakan kredensial yang Anda berikan ke gcloud CLI.
Untuk mengetahui informasi selengkapnya, lihat Melakukan autentikasi untuk menggunakan REST dalam dokumentasi autentikasi Google Cloud .
Untuk mengetahui informasi tentang cara menyiapkan autentikasi bagi lingkungan produksi, lihat Menyiapkan Kredensial Default Aplikasi untuk kode yang berjalan di Google Cloud dalam dokumentasi autentikasi Google Cloud .

Peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan App Topology API, minta administrator untuk memberi Anda peran IAM berikut:

Menjalankan kueri: App Topology Viewer (roles/apptopology.viewer) pada project tempat Anda ingin menggunakan App Topology

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses ke project, folder, dan organisasi.

Peran bawaan ini berisi izin yang diperlukan untuk menggunakan App Topology API. Untuk melihat izin yang benar-benar diperlukan, perluas bagian Izin yang diperlukan:

Izin yang diperlukan

Izin berikut diperlukan untuk menggunakan App Topology API:

Mendapatkan domain:
- apptopology.domains.get
- apptopology.domains.list
Mendapatkan skema: apptopology.schemas.get
Mendapatkan data resource yang ditemukan: apptopology.discoveredResourcesTopologies.generate
Mendapatkan data domain DevOps: apptopology.devOpsDomainTopologies.generate
Mendapatkan data domain Keamanan: apptopology.securityDomainTopologies.generate
Mendapatkan data domain SRE (semua data yang didukung): apptopology.sreDomainTopologies.generate

Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

Mencantumkan domain

Domain adalah kumpulan data resource yang berfokus pada jenis kueri tertentu.

Untuk membuat kueri semua data yang didukung oleh App Topology, gunakan domain SRE.
Untuk mendapatkan data tentang resource agentik, Anda harus menggunakan domain SRE.
Semua contoh respons permintaan dalam dokumen ini menggunakan domain SRE.

Jika perlu, Anda dapat mencantumkan domain yang tersedia dalam project.

gcloud

Mencantumkan domain

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda

Jalankan perintah gcloud app-topology domains list:

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

Anda akan melihat respons seperti berikut:

NAME
DEVOPS
SECURITY
SRE

REST

Mencantumkan domain

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda

Metode HTTP dan URL:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login, atau dengan menggunakan Cloud Shell, yang secara otomatis membuat Anda login ke gcloud CLI. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

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)

Catatan: Perintah berikut mengasumsikan bahwa Anda telah login ke gcloud CLI menggunakan akun pengguna Anda dengan menjalankan gcloud init atau gcloud auth login. Anda dapat memeriksa akun yang saat ini aktif dengan menjalankan gcloud auth list.

Jalankan perintah berikut:

$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

Anda akan melihat respons JSON seperti berikut:

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

Mendapatkan skema

Untuk membantu Anda membuat kueri, Anda bisa mendapatkan daftar semua node, tepi, dan properti yang didukung untuk suatu domain. REST API juga memungkinkan Anda mendapatkan sebagian skema.

Permintaan untuk skema lengkap dapat memerlukan waktu yang jauh lebih lama daripada permintaan untuk skema parsial karena banyaknya item dalam skema.

Mendapatkan skema lengkap

gcloud

Mendapatkan skema lengkap

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda
DOMAIN: Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung.

Jalankan perintah gcloud app-topology domains schema describe:

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

Contoh kutipan berikut dari respons hanya mencakup item pertama dalam skema untuk jenis node, jenis edge, aturan edge, dan properti label.

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

Mendapatkan skema lengkap

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda
DOMAIN: Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung.

Metode HTTP dan URL:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Jalankan perintah berikut:

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)

Jalankan perintah berikut:

$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

Kutipan contoh berikut dari respons hanya menyertakan item pertama dalam skema untuk jenis node, jenis edge, aturan edge, dan properti label.

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

Mendapatkan skema parsial

Anda bisa mendapatkan sebagian skema domain dalam jumlah lompatan tertentu dari label awal yang ditentukan.

Contoh perintah dalam petunjuk ini mengambil sebagian skema yang dimulai di node Base/Agent, dengan kedalaman 1 dan ukuran halaman 5.

Mendapatkan skema parsial

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda
DOMAIN: Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

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

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

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)

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

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

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

$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

Dalam respons, urutan nodeTypes dan edgeTypes konsisten, tetapi urutan labelProperties dapat bervariasi dari permintaan ke permintaan.

Luaskan judul Respons untuk melihat contoh respons.

Respons

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

Menjalankan kueri

Saat menjalankan kueri, Anda menentukan pola kueri yang mencakup node, tepi, dan properti yang ingin Anda telusuri.

Pola kueri didasarkan pada sintaksis pemfilteran AIP-160. Untuk mengetahui ringkasan pola kueri dan batasan kueri, lihat Tentang kueri. Petunjuk ini mengasumsikan bahwa Anda telah membaca informasi struktur dan batasan kueri.

Petunjuk berikut menggunakan contoh kueri untuk semua layanan dan beban kerja App Hub dalam project yang ditentukan, termasuk yang terdaftar (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) dan yang ditemukan (Base/DiscoveredService, Base/DiscoveredWorkload).

Perintah menentukan pola kueri dalam file JSON. File ini sedikit berbeda untuk permintaan gcloud CLI dan REST dalam petunjuk ini.

Untuk gcloud CLI, tentukan domain yang akan dikueri sebagai parameter perintah. Domain tidak disertakan dalam file pola kueri.
Untuk permintaan REST, tentukan domain dan pola kueri dalam isi JSON permintaan. Tetapkan domain di kolom topologyDomains dan tentukan pola kueri di objek filter.

gcloud

Buat topologi

Sebelum menggunakan salah satu data perintah di bawah, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda
DOMAIN: Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung.

Simpan konten berikut ini dalam file yang bernama request.json:

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

Jalankan perintah gcloud app-topology resources-graph generate:

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

Kutipan contoh respons berikut menunjukkan 2 node pertama. Node ini adalah server MCP. Server MCP Google memiliki label Base/DiscoveredService, yang merupakan salah satu label dalam pola kueri.

Dalam output, variabel berikut mewakili nilai yang terkait dengan project yang Anda tentukan dengan PROJECT_ID:

PROJECT_NUMBER - Nomor project untuk project yang ditentukan.
ORGANIZATION_NUMBER - Nomor organisasi untuk organisasi Google Cloud yang berisi project yang ditentukan.

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

Buat topologi

Sebelum menggunakan salah satu data permintaan, lakukan penggantian berikut:

PROJECT_ID: Project ID Anda
DOMAIN: Domain yang ingin Anda kueri. Domain SRE mencakup semua data yang didukung.

Metode HTTP dan URL:

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

Meminta isi JSON:

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

Untuk mengirim permintaan Anda, perluas salah satu opsi berikut:

curl (Linux, macOS, atau Cloud Shell)

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

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

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

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)

Simpan isi permintaan dalam file bernama request.json. Jalankan perintah berikut di terminal untuk membuat atau menimpa file ini di direktori saat ini:

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

Kemudian jalankan perintah berikut untuk mengirim permintaan REST Anda:

$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

Kutipan contoh respons berikut menunjukkan 2 node pertama. Node ini adalah server MCP. Server MCP Google memiliki label Base/DiscoveredService, yang merupakan salah satu label dalam pola kueri.

Dalam output, variabel berikut mewakili nilai yang terkait dengan project yang Anda tentukan dengan PROJECT_ID:

PROJECT_NUMBER - Nomor project untuk project yang ditentukan.
ORGANIZATION_NUMBER - Nomor organisasi untuk organisasi Google Cloud yang berisi project yang ditentukan.

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

Untuk contoh pola kueri tambahan, lihat Contoh pola kueri.

Contoh pola kueri

Gunakan contoh pola kueri berikut untuk membantu Anda membuat pola kueri sendiri untuk menjalankan kueri. Semua contoh di bagian ini menggunakan format JSON.

VM dengan grup instance, jaringan, dan disk

Kueri untuk instance Compute Engine dalam grup instance dengan jaringan dan disk.

Pola dimulai di Base/compute.googleapis.com/Instance dan memiliki tiga cabang edge utama di bawah objek neighbors tingkat teratas yang menentukan kriteria ini:

Instance yang termasuk dalam grup instance terkelola
Instance dengan jaringan yang terhubung
Instance dengan Persistent Disk

Karena cabang digabungkan dengan AND, respons hanya menyertakan instance yang termasuk dalam grup instance terkelola dan memiliki jaringan serta disk.

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

Sumber daya agentic

Buat kueri untuk resource agentik dan hubungannya menggunakan informasi dari Agent Registry, termasuk data untuk agen, server MCP, endpoint, dan keterampilan.

{
  "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 mendukung dua jenis endpoint:

Base/aiplatform.googleapis.com/Endpoint adalah endpoint model Gemini Enterprise Agent Platform.
Base/Endpoint adalah URL target untuk agen, dan merupakan label pada layanan Pendaftaran Agen (Base/agentregistry.googleapis.com/Service). Karena Base/agentregistry.googleapis.com/Service disertakan dalam pola kueri, endpoint agen disertakan dalam hasil respons kueri.

Traffic agen

Kueri untuk traffic antara agen dan agen lain atau server MCP menggunakan data dari Cloud Trace. Setiap edge mencakup data tingkat error dan latensi 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"
          }
        }
      }
    }
  ]
}

Langkah berikutnya

Pelajari cara menggunakan server MCP jarak jauh.
Pelajari cara menjalankan kueri di Cloud Hub.
Pelajari cara menjalankan kueri di Gemini Enterprise Agent Platform.

Menggunakan App Topology API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Ringkasan

Sebelum memulai

gcloud

REST

Peran yang diperlukan

Izin yang diperlukan

Mencantumkan domain

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Mendapatkan skema

Mendapatkan skema lengkap

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Mendapatkan skema parsial

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Respons

Menjalankan kueri

gcloud

Linux, macOS, atau Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, atau Cloud Shell)

PowerShell (Windows)

Contoh pola kueri

VM dengan grup instance, jaringan, dan disk

Sumber daya agentic

Traffic agen

Langkah berikutnya

Menggunakan App Topology API