App Topology API 사용

REST API 또는 Google Cloud CLI를 사용하여 Google Cloud 전반에서 데이터를 상호 연관시키는 쿼리를 프로그래매틱 방식으로 실행할 수 있습니다.

개요

App Topology API 쿼리를 실행하면 API는 쿼리와 일치하는 그래프 노드(리소스) 및 가장자리 (관계) 목록을 반환합니다. 앱 토폴로지는 다음과 같은 Google Cloud 서비스의 데이터를 결합합니다.

• Cloud 애셋 인벤토리, App Hub, 에이전트 레지스트리의 리소스 메타데이터
• 컨테이너 이미지의 Git 커밋 또는 빌드 출처 기록과 같은 배포 데이터
• 취약점 또는 Identity and Access Management (IAM) 소유권과 같은 Security Command Center의 보안 데이터
• 트레이스 및 알림과 같은 Google Cloud Observability 데이터

쿼리를 실행하려면 다음 정보가 필요합니다.

• 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다. 사용 가능한 도메인을 나열하는 방법을 알아보려면 도메인 나열을 참고하세요.
• 쿼리에 포함할 수 있는 지원되는 그래프 노드, 에지, 속성입니다. 도메인의 전체 또는 부분 스키마를 가져올 수 있습니다. 자세한 내용은 스키마 가져오기를 참고하세요.
• 검색하려는 노드와 에지가 포함된 쿼리 패턴입니다. 쿼리 실행을 참고하세요.

시작하기 전에

1. 앱 토폴로지 설정

2. 이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

   gcloud

   Google Cloud 콘솔에서 Cloud Shell을 활성화합니다.

   Cloud Shell 활성화

   Google Cloud 콘솔 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. Cloud Shell은 Google Cloud CLI가 사전 설치된 셸 환경으로, 현재 프로젝트의 값이 이미 설정되어 있습니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

   REST

   로컬 개발 환경에서 이 페이지의 REST API 샘플을 사용하려면 gcloud CLI에 제공한 사용자 인증 정보를 사용합니다.

   Google Cloud CLI를 설치합니다.

   외부 ID 공급업체(IdP)를 사용하는 경우 먼저 제휴 ID로 gcloud CLI에 로그인해야 합니다.

   자세한 내용은 Google Cloud 인증 문서의 REST 사용을 위한 인증을 참조하세요.

   프로덕션 환경의 인증 설정에 대한 자세한 내용은 Google Cloud 인증 문서의 Google Cloud에서 실행되는 코드의 애플리케이션 기본 사용자 인증 정보 설정 을 참고하세요.

필요한 역할

앱 토폴로지 API를 사용하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 쿼리 실행: 앱 토폴로지를 사용하려는 프로젝트에 대한 앱 토폴로지 뷰어 (roles/apptopology.viewer)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 App Topology API를 사용하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

앱 토폴로지 API를 사용하려면 다음 권한이 필요합니다.

• 도메인 가져오기:
  • apptopology.domains.get
  • apptopology.domains.list
• 스키마 가져오기: apptopology.schemas.get
• 발견된 리소스 데이터 가져오기: apptopology.discoveredResourcesTopologies.generate
• DevOps 도메인 데이터 가져오기: apptopology.devOpsDomainTopologies.generate
• 보안 도메인 데이터 가져오기: apptopology.securityDomainTopologies.generate
• SRE 도메인 데이터 (지원되는 모든 데이터) 가져오기: apptopology.sreDomainTopologies.generate

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

도메인 나열

도메인은 특정 유형의 쿼리에 중점을 둔 리소스 데이터 세트입니다.

• 앱 토폴로지에서 지원하는 모든 데이터를 쿼리하려면 SRE 도메인을 사용하세요.
• 에이전트 리소스에 관한 데이터를 가져오려면 SRE 도메인을 사용해야 합니다.
• 이 문서의 모든 요청 응답 예시에서는 SRE 도메인을 사용합니다.

필요한 경우 프로젝트에서 사용할 수 있는 도메인을 나열할 수 있습니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID

gcloud app-topology domains list 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud app-topology domains list --project=PROJECT_ID

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud app-topology domains list --project=PROJECT_ID

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud app-topology domains list --project=PROJECT_ID

다음과 비슷한 응답이 표시됩니다.

NAME
DEVOPS
SECURITY
SRE

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID

HTTP 메서드 및 URL:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

$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

다음과 비슷한 JSON 응답이 표시됩니다.

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

스키마 가져오기

쿼리를 작성하는 데 도움이 되도록 도메인에 대해 지원되는 모든 노드, 에지, 속성의 목록을 가져올 수 있습니다. REST API를 사용하면 스키마의 일부를 가져올 수도 있습니다.

전체 스키마 요청은 스키마의 항목 수가 많기 때문에 부분 스키마 요청보다 훨씬 오래 걸릴 수 있습니다.

전체 스키마 가져오기

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DOMAIN: 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다.

gcloud app-topology domains schema describe 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

다음은 응답에서 발췌한 예시로, 노드 유형, 에지 유형, 에지 규칙, 라벨 속성의 스키마에 있는 첫 번째 항목만 포함됩니다.

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

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DOMAIN: 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다.

HTTP 메서드 및 URL:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

$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

다음은 응답에서 발췌한 예로, 노드 유형, 에지 유형, 에지 규칙, 라벨 속성의 스키마에 있는 첫 번째 항목만 포함됩니다.

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

부분 스키마 가져오기

지정된 시작 라벨에서 지정된 홉 수 이내에 있는 도메인 스키마의 일부를 가져올 수 있습니다.

이 안내의 예시 명령어는 Base/Agent 노드에서 시작하는 스키마의 일부를 가져오며, 깊이는 1이고 페이지 크기는 5입니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DOMAIN: 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다.

HTTP 메서드 및 URL:

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

JSON 요청 본문:

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

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

그런 후 다음 명령어를 실행하여 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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

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

그런 후 다음 명령어를 실행하여 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

대답에서 nodeTypes 및 edgeTypes의 순서는 일관되지만 labelProperties의 순서는 요청마다 다를 수 있습니다.

응답 제목을 펼쳐 응답 예시를 확인합니다.

응답

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

쿼리 실행

쿼리를 실행할 때는 검색하려는 노드, 가장자리, 속성이 포함된 쿼리 패턴을 지정합니다.

쿼리 패턴은 AIP-160 필터링 구문을 기반으로 합니다. 쿼리 패턴 및 쿼리 제한사항에 대한 개요는 쿼리 정보를 참고하세요. 이 안내에서는 쿼리 구조 및 제한사항 정보를 읽었다고 가정합니다.

다음 안내에서는 등록된 서비스 (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload)와 검색된 서비스(Base/DiscoveredService, Base/DiscoveredWorkload)를 비롯하여 지정된 프로젝트의 모든 App Hub 서비스 및 워크로드에 대한 예시 쿼리를 사용합니다.

명령어는 JSON 파일에서 쿼리 패턴을 지정합니다. 이 안내의 gcloud CLI 및 REST 요청의 파일은 약간 다릅니다.

• gcloud CLI의 경우 쿼리할 도메인을 명령어의 매개변수로 지정합니다. 도메인이 쿼리 패턴 파일에 포함되어 있지 않습니다.
• REST 요청의 경우 요청의 JSON 본문에 도메인과 쿼리 패턴을 모두 지정합니다. topologyDomains 필드에서 도메인을 설정하고 filter 객체 아래에서 쿼리 패턴을 지정합니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DOMAIN: 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다.

다음 콘텐츠를 request.json 파일에 저장합니다.

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

gcloud app-topology resources-graph generate 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

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

다음 예시 응답 발췌문에서는 처음 2개 노드를 보여줍니다. 이러한 노드는 MCP 서버입니다. Google MCP 서버에는 Base/DiscoveredService 라벨이 있으며, 이는 쿼리 패턴의 라벨 중 하나입니다.

출력에서 다음 변수는 PROJECT_ID로 지정한 프로젝트와 연결된 값을 나타냅니다.

• PROJECT_NUMBER - 지정된 프로젝트의 프로젝트 번호입니다.
• ORGANIZATION_NUMBER - 지정된 프로젝트가 포함된 Google Cloud 조직의 조직 번호입니다.

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

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• DOMAIN: 쿼리할 도메인입니다. SRE 도메인에는 지원되는 모든 데이터가 포함됩니다.

HTTP 메서드 및 URL:

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

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

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

cURL(Linux, macOS, Cloud Shell)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장합니다. 터미널에서 다음 명령어를 실행하여 현재 디렉터리에 이 파일을 만들거나 덮어씁니다.

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

그런 후 다음 명령어를 실행하여 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)

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.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"
      }
    }
  }
}
'@  | Out-File -FilePath request.json -Encoding utf8

그런 후 다음 명령어를 실행하여 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

다음 예시 응답 발췌문에서는 처음 2개 노드를 보여줍니다. 이러한 노드는 MCP 서버입니다. Google MCP 서버에는 Base/DiscoveredService 라벨이 있으며, 이는 쿼리 패턴의 라벨 중 하나입니다.

출력에서 다음 변수는 PROJECT_ID로 지정한 프로젝트와 연결된 값을 나타냅니다.

• PROJECT_NUMBER - 지정된 프로젝트의 프로젝트 번호입니다.
• ORGANIZATION_NUMBER - 지정된 프로젝트가 포함된 Google Cloud 조직의 조직 번호입니다.

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

추가 쿼리 패턴 예시는 쿼리 패턴 예시를 참고하세요.

쿼리 패턴 예시

다음 쿼리 패턴 예시를 사용하여 쿼리 실행을 위한 자체 쿼리 패턴을 빌드하세요. 이 섹션의 모든 예시에서는 JSON 형식을 사용합니다.

인스턴스 그룹, 네트워크, 디스크가 있는 VM

네트워킹 및 디스크가 있는 인스턴스 그룹의 Compute Engine 인스턴스를 쿼리합니다.

패턴은 Base/compute.googleapis.com/Instance에서 시작하며 최상위 neighbors 객체 아래에 이러한 기준을 정의하는 세 개의 기본 edge 브랜치가 있습니다.

• 관리형 인스턴스 그룹에 속한 인스턴스
• 연결된 네트워크가 있는 인스턴스
• Persistent Disk가 있는 인스턴스

브랜치가 AND와 결합되므로 응답에는 관리형 인스턴스 그룹에 속하고 네트워크와 디스크가 모두 있는 인스턴스만 포함됩니다.

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

에이전트형 리소스

에이전트, MCP 서버, 엔드포인트, 스킬의 데이터를 비롯한 에이전트 레지스트리의 정보를 사용하여 에이전트 리소스와 그 관계를 쿼리합니다.

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

앱 토폴로지는 두 가지 유형의 엔드포인트를 지원합니다.

• Base/aiplatform.googleapis.com/Endpoint은 Gemini Enterprise Agent Platform 모델 엔드포인트입니다.
• Base/Endpoint는 에이전트의 타겟 URL이며 Agent Registry 서비스 (Base/agentregistry.googleapis.com/Service)의 라벨입니다. Base/agentregistry.googleapis.com/Service가 쿼리 패턴에 포함되므로 Agent Endpoint가 쿼리 응답 결과에 포함됩니다.

에이전트 트래픽

Cloud Trace의 데이터를 사용하여 에이전트와 다른 에이전트 또는 MCP 서버 간의 트래픽을 쿼리합니다. 각 에지에는 오류율과 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"
          }
        }
      }
    }
  ]
}

다음 단계

• 원격 MCP 서버 사용에 대해 알아봅니다.
• Cloud Hub에서 쿼리를 실행하는 방법을 알아봅니다.
• Gemini Enterprise Agent Platform에서 쿼리를 실행하는 방법을 알아봅니다.