‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

שימוש ב-App Topology API

אפשר להריץ שאילתות באופן פרוגרמטי כדי ליצור קורלציה בין נתונים ב- Google Cloud באמצעות API בארכיטקטורת REST או Google Cloud CLI.

סקירה כללית

כשמריצים שאילתה ב-App Topology API, ה-API מחזיר רשימה של צמתי גרף (משאבים) וקשתות (קשרים) שתואמים לשאילתה. App Topology משלבת נתונים מ Google Cloud שירותים כמו:

מטא-נתונים של משאבים ממאגר משאבי הענן, מ-App Hub ומ-Agent Registry
נתוני פריסה, כמו קומיט ב-Git או אישור המקור של Build של קובץ אימג' של קונטיינר
נתוני אבטחה מ-Security Command Center, כמו נקודות חולשה או בעלות על ניהול זהויות וגישה (IAM)
נתונים של Google Cloud Observability, כמו עקבות והתראות

כדי להריץ שאילתה, צריך את הפרטים הבאים:

הדומיין שרוצים לשלוח לו שאילתה. הדומיין SRE כולל את כל הנתונים הנתמכים. ראו רשימת דומיינים למידע ולמידה על רישום דומיינים זמינים.
הצמתים, הקצוות והמאפיינים הנתמכים של הגרף שאפשר לכלול בשאילתה. אפשר לקבל את הסכימה המלאה או החלקית של דומיין. פרטים נוספים זמינים במאמר בנושא קבלת הסכימה.
תבנית השאילתה עם הצמתים והקצוות שרוצים לחפש. איך מריצים שאילתות

לפני שמתחילים

הגדרת App Topology
צריך לבחור את הכרטיסייה הרלוונטית לאופן שבו תכננתם להשתמש בדוגמאות בדף הזה:
gcloud

במסוף Google Cloud , מפעילים את Cloud Shell.

הפעלת Cloud Shell

בחלק התחתון של Google Cloud המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.
REST

כדי להשתמש בסביבת פיתוח מקומית בדוגמאות של API בארכיטקטורת REST שבדף הזה, צריך להשתמש בפרטי הכניסה שאתם נותנים ל-CLI של gcloud.
מידע נוסף מופיע במאמר אימות לשימוש ב-REST במסמכי האימות של Google Cloud .
למידע נוסף על הגדרת אימות בסביבת ייצור, ראו את המאמר בנושא הגדרת Application Default Credentials לקוד שפועל ב- Google Cloud במאמרי העזרה בנושא אימות ב- Google Cloud .

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות לשימוש ב-App Topology API, אתם צריכים לבקש מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

להריץ שאילתות: App Topology Viewer (roles/apptopology.viewer) בפרויקטים שבהם רוצים להשתמש ב-App Topology

להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

התפקידים המוגדרים מראש האלה מכילים את ההרשאות שנדרשות לשימוש ב-App Topology API. כדי לראות בדיוק אילו הרשאות נדרשות, אפשר להרחיב את הקטע ההרשאות הנדרשות:

ההרשאות הנדרשות

כדי להשתמש ב-App Topology API, נדרשות ההרשאות הבאות:

קבלת דומיינים:
- apptopology.domains.get
- apptopology.domains.list
קבלת סכימות: apptopology.schemas.get
קבלת נתונים של משאב שזוהה: apptopology.discoveredResourcesTopologies.generate
קבלת נתוני דומיין של DevOps: apptopology.devOpsDomainTopologies.generate
קבלת נתונים של דומיין אבטחה: apptopology.securityDomainTopologies.generate
קבלת נתוני דומיין של SRE (כל הנתונים הנתמכים): apptopology.sreDomainTopologies.generate

יכול להיות שתקבלו את ההרשאות האלה באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש אחרים.

רשימת הדומיינים

דומיינים הם קבוצות של נתוני משאבים שמתמקדות בסוגים ספציפיים של שאילתות.

כדי לשלוח שאילתות לגבי כל הנתונים שנתמכים על ידי App Topology, משתמשים בדומיין SRE.
כדי לקבל נתונים על משאבים מבוססי-סוכן, צריך להשתמש בדומיין SRE.
כל הדוגמאות לתגובות לבקשות במסמך הזה משתמשות בדומיין SRE.

במקרה הצורך, אפשר לפרט את הדומיינים שזמינים בפרויקט.

gcloud

רשימת הדומיינים

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט

מריצים את הפקודה gcloud app-topology domains list:

‫Linux,‏ macOS או 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

אמורים לקבל תגובה שדומה לזו:

NAME
DEVOPS
SECURITY
SRE

REST

רשימת הדומיינים

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט

ה-method של ה-HTTP וכתובת ה-URL:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה 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)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה 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"
    }
  ]
}

קבלת הסכימה

כדי לעזור לכם ליצור את השאילתות, אתם יכולים לקבל רשימה של כל הצמתים, הקצוות והמאפיינים הנתמכים בדומיין. ה-API בארכיטקטורת REST מאפשר גם לקבל חלק מהסכימה.

בקשות לסכימה מלאה עשויות להימשך זמן רב יותר מבקשות לסכימה חלקית, בגלל מספר הפריטים הגדול בסכימה.

קבלת הסכימה המלאה

gcloud

קבלת סכימה מלאה

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: מזהה הפרויקט
‫DOMAIN: הדומיין שרוצים לשלוח אליו שאילתה. הדומיין SRE כולל את כל הנתונים הנתמכים.

מריצים את הפקודה gcloud app-topology domains schema describe:

‫Linux,‏ macOS או 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

הקטע הבא מתוך תשובה לדוגמה כולל רק את הפריט הראשון בסכימה של סוגי צמתים, סוגי קצוות, כללי קצוות ומאפייני תוויות.

{
  "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: מזהה הפרויקט
‫DOMAIN: הדומיין שרוצים לשלוח אליו שאילתה. הדומיין SRE כולל את כל הנתונים הנתמכים.

ה-method של ה-HTTP וכתובת ה-URL:

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

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

מריצים את הפקודה הבאה:

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)

מריצים את הפקודה הבאה:

$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: מזהה הפרויקט
‫DOMAIN: הדומיין שרוצים לשלוח אליו שאילתה. הדומיין SRE כולל את כל הנתונים הנתמכים.

ה-method של ה-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)

שומרים את גוף הבקשה בקובץ בשם 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)

@'
{
  "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. סקירה כללית של מבני שאילתות ומגבלות על שאילתות מופיעה במאמר מידע על שאילתות. ההוראות האלה מניחות שקראתם את המידע על מבנה השאילתות וההגבלות.

בהוראות הבאות נעשה שימוש בשאילתה לדוגמה לכל השירותים ועומסי העבודה של App Hub בפרויקט שצוין, כולל אלה שרשומים (Base/apphub.googleapis.com/Service, Base/apphub.googleapis.com/Workload) ואלה שזוהו (Base/DiscoveredService, Base/DiscoveredWorkload).

בפקודות מציינים את תבנית השאילתה בקובץ JSON. הקובץ שמופיע בהוראות האלה שונה מעט עבור בקשות ה-CLI של gcloud ובקשות REST.

ב-CLI של gcloud, מציינים את הדומיין שאותו רוצים לשלוח כפרמטר של הפקודה. הדומיין לא נכלל בקובץ של מבני השאילתות.
בבקשות REST, מציינים גם את הדומיין וגם את תבנית השאילתה בגוף ה-JSON של הבקשה. מגדירים את הדומיין בשדה topologyDomains ומציינים את תבנית השאילתה באובייקט filter.

gcloud

יצירת טופולוגיה

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫PROJECT_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 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

בדוגמה הבאה מוצג קטע מהתגובה עם 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: מזהה הפרויקט
‫DOMAIN: הדומיין שרוצים לשלוח אליו שאילתה. הדומיין SRE כולל את כל הנתונים הנתמכים.

ה-method של ה-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)

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)

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

בפלט, המשתנים הבאים מייצגים ערכים שמשויכים לפרויקט שציינתם באמצעות 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.

מכונות וירטואליות עם קבוצות מכונות, רשתות ודיסקים

שאילתה לגבי מכונות Compute Engine בקבוצת מכונות עם רשת ודיסק.

התבנית מתחילה ב-Base/compute.googleapis.com/Instance ויש לה שלושה ענפים edge ראשיים מתחת לאובייקט ברמה העליונה neighbors שמגדירים את הקריטריונים האלה:

מופעים ששייכים לקבוצה של מופעי מכונה מנוהלים
מופעים עם רשת מחוברת
מכונות וירטואליות עם 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"
          }
        }
      }
    }
  ]
}

משאבים באמצעות סוכנים

יצירת שאילתות לגבי משאבים מבוססי-סוכנים והקשרים ביניהם באמצעות מידע מ-Agent Registry, כולל נתונים של סוכנים, שרתי 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"
    }
  }
}

ב-App Topology יש תמיכה בשני סוגים של נקודות קצה:

‫Base/aiplatform.googleapis.com/Endpoint היא נקודת קצה של מודל ב-Gemini Enterprise Agent Platform.
‫Base/Endpoint היא כתובת היעד של Agent Endpoint‏, והיא תווית בשירות Agent Registry‏ (Base/agentregistry.googleapis.com/Service). מכיוון ש-Base/agentregistry.googleapis.com/Service כלול בתבנית השאילתה, Agent Endpoints כלולים בתוצאות התשובה לשאילתה.

תנועת סוכנים

אפשר להריץ שאילתה כדי לראות את התעבורה בין סוכנים לבין סוכנים אחרים או שרתי MCP באמצעות נתונים מ-Cloud Trace. כל קצה כולל נתונים של שיעור השגיאות וחביון 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

שימוש ב-App Topology API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

סקירה כללית

לפני שמתחילים

gcloud

REST

התפקידים הנדרשים

ההרשאות הנדרשות

רשימת הדומיינים

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

קבלת הסכימה

קבלת הסכימה המלאה

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

קבלת סכימה חלקית

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

תשובה

הרצת שאילתות

gcloud

‫Linux,‏ macOS או Cloud Shell

‏Windows (PowerShell)

Windows‏ (cmd.exe)

REST

‫Curl (Linux,‏ macOS או Cloud Shell)

‎PowerShell (Windows)

דוגמאות למבני שאילתות

מכונות וירטואליות עם קבוצות מכונות, רשתות ודיסקים

משאבים באמצעות סוכנים

תנועת סוכנים

המאמרים הבאים

שימוש ב-App Topology API