关于查询

本文档介绍了 App Topology 查询的组成部分和查询语法。

查询组件

App Topology 查询包含多个组成部分：

  • 节点 - 在 App Hub 或 Agent Registry 中发现或注册的 Google Cloud 资源。节点的示例包括

    • Compute Engine 虚拟机
    • Artifact Registry 中的容器映像
    • 代理
    • Cloud Monitoring 提醒
    • App Hub 应用、服务或工作负载
    • 漏洞

    您可以查询的资源取决于您选择的网域。SRE 网域包含所有受支持的资源。

  • 属性：可用于优化查询的节点的属性。例如，您可以查询具有特定 CVE ID 的漏洞。

  • 边：两个节点之间的定向关系。

查询结构

本部分简要介绍了查询结构。如需了解详情，请参阅 generate_discovered_resources_topology 工具的参考文档。

查询使用 AIP-160 过滤语法。

查询的关键要素包括：

  • 查询以指定根节点的 startingNode 开头。
  • 您可以使用 neighbor 定义与根 startingNode 的关系。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 运算符，但您不能在单个匹配表达式中混用这两种类型的运算符。

示例：

  • 匹配 App Hub 工作负载："Base/apphub.googleapis.com/Workload"
  • 匹配发现的工作负载或服务："Base/DiscoveredWorkload OR Base/DiscoveredService"

匹配的房源

使用 property_matcher_expr 匹配表达式过滤节点的属性。

属性分为两种类型：

  • 内置系统属性 - 适用于所有节点和边的属性：
    • 对于节点：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 方法会返回这些属性。

    例如，如需过滤出标签为 n 且位于 us-central1 区域的资源，请使用表达式 n.Base/location = "us-central1"。

如需查看属性匹配表达式中支持的运算符列表，请参阅 LabelPropertiesPattern。

边缘方向

对于边，edge.direction 指定方向，默认值为 DIRECTION_UNSPECIFIED。您可以设置以下某个值来指明源节点与目标节点之间的关系。

  • TO - 从来源到目的地。
  • FROM - 从目的地到来源。
  • ANY - 节点之间的关系是双向的。

如果方向已知，请使用 TO 或 FROM。双向查询 "ANY" 会以组合方式扩展遍历状态，并增加 API 延迟时间。

限制

查询和拓扑大小：

  • 如果查询更复杂，返回结果所需的时间可能会更长。这包括以下条件：
    • propertyMatcherExpr 包含 4 个以上的比较对象。
    • 拓扑遍历在查询执行中包含五个以上的跃点。
  • 返回的拓扑数据不支持分页。
  • 该 API 最多返回 1,000 条唯一路径。
  • 对于可观测性数据：
    • Observability/Alert 节点仅支持等式 (=) 运算符。
    • Observability/SENDS_TRAFFIC 边缘不支持属性过滤条件。

数据可用性：

  • Google Cloud Observability 不支持所有 App Hub 服务和工作负载的遥测。如需查看支持的基础设施资源列表，请参阅应用监控支持的基础设施。
  • 查看 App Hub 应用的拓扑时，可视化效果中不包含可在应用之间共享的资源。
  • 删除 Developer Connect 分析洞见事件后，该事件可能仍会在 App Topology 查询结果中显示几天。
  • 对于 Security Command Center 提供的安全和合规性数据：
    • 所提供的数据处于预览版阶段
    • 数据仅适用于组织中的项目和应用。 Google Cloud