クエリについて

このドキュメントでは、アプリ トポロジ クエリのコンポーネントとクエリ構文について説明します。

クエリ コンポーネント

アプリ トポロジ クエリは、次のコンポーネントで構成されます。

  • ノード - 検出された Google Cloud リソース、または App Hub または Agent Registry に登録されたリソース。ノードの例としては、次のようなものがあります。

    • Compute Engine VM
    • Artifact Registry のコンテナ イメージ
    • エージェント
    • Cloud Monitoring のアラート
    • App Hub のアプリケーション、サービス、ワークロード
    • 脆弱性

    クエリできるリソースは、選択したドメインによって異なります。SRE ドメインには、サポートされているすべてのリソースが含まれます。

  • プロパティ: クエリの絞り込みに使用できるノードのプロパティ。たとえば、特定の CVE ID を持つ脆弱性をクエリできます。

  • エッジ: 2 つのノード間の方向性のある関係。

クエリの構造

このセクションでは、クエリ構造の概要について説明します。詳細については、generate_discovered_resources_topology ツールのリファレンス ドキュメントをご覧ください。

クエリでは AIP-160 フィルタリング構文が使用されます。

クエリの主な要素は次のとおりです。

  • クエリは、ルートノードを指定する startingNode で始まります。
  • ルート startingNode との関係は、neighbor を使用して定義します。neighbor 要素は、接続されたノードとエッジを定義します。
  • LabelPropertiesPattern は、一致式を指定します。
    • label_matcher_expr - ノードまたはエッジラベルの一致式。
    • property_matcher_expr - ノードまたはエッジの特定のプロパティをフィルタする一致式。
  • 方向性のある関係は、direction フィールドを使用して定義します。

次の例は、プロジェクト web-project の App Hub ワークロード foo に関連付けられたアラートのクエリを示しています。また、alias を使用してノードにラベルを付け、後続の式で参照しやすくする方法も示しています。

{
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
  "name": "generate_discovered_resource_topology",
  "arguments": {
    "name": "projects/web-project/locations/global/discoveredResourcesTopology",
    "topologyDomains": ["projects/web-project/locations/global/domains/SRE"],
    "filter": {
        "startingNode": {
        "alias": "source",
        "labelPropertiesPattern": {
          "labelMatcherExpr": "Base/apphub.googleapis.com/Workload",
          "propertyMatcherExpr": "source.Base/app/workloadReferenceUri = 'foo'"
        }
      },
      "neighbors": [
          {
          "edge": {
            "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/HAS_ALERT"
            },
            "direction": "TO"
          },
          "graph": {
              "startingNode": {
              "alias": "alert",
              "labelPropertiesPattern": {
                "labelMatcherExpr": "Observability/Alert"
              }
            }
          }
        }
      ]
    }
  }
},
}

一致するノード

label_matcher_expr マッチ式を使用してリソースタイプ（ノード）を指定します。単一のノードタイプまたは複数のタイプを照合できます。

label_matcher_expr では OR 演算子または AND 演算子のいずれかを使用できますが、1 つのマッチ式で両方のタイプの演算子を混在させることはできません。

例:

  • App Hub ワークロードを照合: "Base/apphub.googleapis.com/Workload"
  • 検出されたワークロードまたはサービスを照合する: "Base/DiscoveredWorkload OR Base/DiscoveredService"

一致する宿泊施設

property_matcher_expr 一致式を使用してノードの属性をフィルタします。

プロパティには次の 2 種類があります。

  • 組み込みシステム プロパティ - すべてのノードとエッジに適用されるプロパティ:
    • ノードの場合: NodeName（ノードの場合）
    • エッジの場合: EdgeName（エッジの場合）

  • ラベル - プロパティ フィルタ式で使用できるノードまたはエッジのラベルのリスト。次に例を示します。

    (CONTAINS_ANY(alias.Labels, "Base/MCPServer") AND alias.Base/agentregistry/urn = "foo") OR (CONTAINS_ANY(alias.Labels, "Base/Agent") AND alias.Base/agent/framework = "bar")

  • ドメイン スキーマ プロパティ - Base/location、Observability/errorRate、Base/app/state などのリソースタイプに固有のプロパティ。GetSchema メソッドはこれらのプロパティを返します。

    たとえば、リージョン us-central1 のラベル n を持つリソースをフィルタするには、式 n.Base/location = "us-central1" を使用します。

プロパティ一致式でサポートされている演算子の一覧については、LabelPropertiesPattern をご覧ください。

エッジの方向

エッジの場合、edge.direction は方向を指定します。デフォルトは DIRECTION_UNSPECIFIED です。次のいずれかの値を設定して、送信元ノードと宛先ノードの関係を示すことができます。

  • TO - 送信元から宛先。
  • FROM - 宛先から送信元へ。
  • ANY - ノード間の関係は双方向です。

方向がわかっている場合は、TO または FROM を使用します。双方向クエリ "ANY" は、トラバーサル状態を組み合わせ的に拡張し、API レイテンシを増加させます。

制限事項

クエリとトポロジのサイズ:

  • クエリが複雑な場合、クエリのレスポンスで結果が返されるまでに時間がかかることがあります。これには次の条件が含まれます。
    • propertyMatcherExpr に 4 つ以上の比較が含まれています。
    • トポロジ トラバーサルに、クエリ実行で 6 ホップ以上が含まれている。
  • 返されたトポロジ データではページネーションはサポートされていません。
  • API は最大 1,000 個の一意のパスを返します。
  • オブザーバビリティ データの場合:
    • Observability/Alert ノードは等価（=）演算子のみをサポートします。
    • Observability/SENDS_TRAFFIC エッジはプロパティ フィルタをサポートしていません。

利用できるデータ:

  • Google Cloud Observability は、すべての App Hub サービスとワークロードのテレメトリーをサポートしていません。サポートされているインフラストラクチャ リソースの一覧については、アプリケーションのモニタリングでサポートされているインフラストラクチャをご覧ください。
  • App Hub アプリケーションのトポロジを表示する場合、アプリケーション間で共有できるリソースは可視化に含まれません。
  • Developer Connect の分析情報イベントを削除しても、数日間はアプリ トポロジのクエリ結果にイベントが表示されることがあります。
  • Security Command Center によって提供されるセキュリティとコンプライアンスのデータの場合:
    • 提供されたデータはプレビュー版です
    • データは、 Google Cloud組織内のプロジェクトとアプリケーションでのみ使用できます。