Abfragen

In diesem Dokument werden die Komponenten einer App-Topologie-Abfrage und die Abfragesyntax beschrieben.

Abfragekomponenten

Anwendungstopologie-Abfragen bestehen aus mehreren Komponenten:

  • Knoten: Erkannte Google Cloud Ressourcen oder Ressourcen, die in App Hub oder der Agent Registry registriert sind. Beispiele für Knoten:

    • Eine Compute Engine-VM
    • Ein Container-Image in Artifact Registry
    • KI-Agent
    • Eine Benachrichtigung von Cloud Monitoring
    • Eine App Hub-Anwendung, ein App Hub-Dienst oder eine App Hub-Arbeitslast
    • Eine Sicherheitslücke

    Die Ressourcen, die Sie abfragen können, hängen von der ausgewählten Domain ab. Die Domain SRE umfasst alle unterstützten Ressourcen.

  • Properties: Eigenschaften eines Knotens, mit denen Sie eine Abfrage verfeinern können. Sie können beispielsweise nach einer Sicherheitslücke mit einer bestimmten CVE-ID suchen.

  • Kante: Eine gerichtete Beziehung zwischen zwei Knoten.

Abfragestruktur

In diesem Abschnitt erhalten Sie einen Überblick über die Abfragestruktur. Weitere Informationen finden Sie in der Referenzdokumentation zum Tool „generate_discovered_resources_topology“.

Für Abfragen wird die AIP-160-Filtersyntax verwendet.

Zu den wichtigsten Elementen einer Anfrage gehören:

  • Abfragen beginnen mit einem startingNode, das einen Stammknoten angibt.
  • Sie definieren Beziehungen mit dem Stamm-startingNode mit neighbor. Das neighbor-Element definiert verbundene Knoten und Kanten.
  • LabelPropertiesPattern gibt Abgleichsausdrücke an.
    • label_matcher_expr: Ein Abgleichsausdruck für Knoten- oder Kantenlabels.
    • property_matcher_expr: Ein Abgleichsausdruck zum Filtern nach bestimmten Eigenschaften eines Knotens oder einer Kante.
  • Sie definieren eine gerichtete Beziehung mit dem Feld direction.

Das folgende Beispiel zeigt eine Abfrage für Benachrichtigungen, die mit der App Hub-Arbeitslast foo im Projekt web-project verknüpft sind. Außerdem wird gezeigt, wie alias verwendet wird, um Knoten zu kennzeichnen, damit in nachfolgenden Ausdrücken leichter auf sie verwiesen werden kann.

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

Übereinstimmende Knoten

Geben Sie Ressourcentypen (Knoten) mit dem Abgleichsausdruck label_matcher_expr an. Sie können einen oder mehrere Knotentypen abgleichen.

Für eine label_matcher_expr können entweder OR- oder AND-Operatoren verwendet werden. Sie können aber nicht beide Arten von Operatoren in einem einzelnen Abgleichsausdruck kombinieren.

Beispiele:

  • App Hub-Arbeitslasten abgleichen: "Base/apphub.googleapis.com/Workload"
  • Passende Arbeitslasten oder Dienste finden: "Base/DiscoveredWorkload OR Base/DiscoveredService"

Übereinstimmende Unterkünfte

Filtern Sie Attribute eines Knotens mit dem property_matcher_expr-Abgleichsausdruck.

Es gibt zwei Arten von Properties:

  • Integrierte Systemattribute: Attribute, die für alle Knoten und Kanten gelten:
    • Für Knoten: NodeName (für Knoten)
    • Für Kanten: EdgeName (für Kanten)

  • Labels: Die Liste der Labels für einen Knoten oder eine Kante, die mit Eigenschaftsfilterausdrücken verwendet werden können. Beispiel:

    (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")

  • Domain-Schema-Attribute: Attribute, die für einen Ressourcentyp spezifisch sind, z. B. Base/location, Observability/errorRate und Base/app/state. Die GetSchema-Methode gibt diese Eigenschaften zurück.

    Wenn Sie beispielsweise nach einer Ressource mit dem Label n in der Region us-central1 filtern möchten, verwenden Sie den Ausdruck n.Base/location = "us-central1".

Eine Liste der unterstützten Operatoren in Property-Abgleichsausdrücken finden Sie unter LabelPropertiesPattern.

Edge-Richtung

Bei Kanten gibt edge.direction die Richtung an. Der Standardwert ist DIRECTION_UNSPECIFIED. Sie können einen der folgenden Werte festlegen, um die Beziehung zwischen dem Quellknoten und dem Zielknoten anzugeben.

  • TO: Von der Quelle zum Ziel.
  • FROM – Vom Ziel zur Quelle.
  • ANY – Die Beziehung zwischen Knoten ist bidirektional.

Wenn die Richtung bekannt ist, verwenden Sie TO oder FROM. Bidirektionale Anfragen "ANY" erweitern den Traversierungsstatus kombinatorisch und erhöhen die API-Latenz.

Beschränkungen

Größe von Abfrage und Topologie:

  • Bei komplexeren Anfragen kann es etwas dauern, bis Ergebnisse zurückgegeben werden. Dazu gehören die folgenden Bedingungen:
    • propertyMatcherExpr enthält mehr als vier Vergleiche.
    • Die Topologieüberschreitung umfasst mehr als fünf Hops bei der Ausführung der Abfrage.
  • Die Paginierung wird für zurückgegebene Topologiedaten nicht unterstützt.
  • Die API gibt maximal 1.000 eindeutige Pfade zurück.
  • Für Daten zur Beobachtbarkeit:
    • Observability/Alert-Knoten unterstützen nur den Gleichheitsoperator (=).
    • Observability/SENDS_TRAFFIC-Kanten unterstützen keine Attributfilter.

Datenverfügbarkeit:

  • Google Cloud Observability unterstützt nicht die Telemetrie für alle App Hub-Dienste und ‑Arbeitslasten. Eine Liste der unterstützten Infrastrukturressourcen finden Sie unter Von Application Monitoring unterstützte Infrastruktur.
  • Wenn Sie sich die Topologie einer App Hub-Anwendung ansehen, werden Ressourcen, die für mehrere Anwendungen freigegeben werden können, nicht in der Visualisierung berücksichtigt.
  • Wenn Sie ein Developer Connect-Insights-Ereignis löschen, wird es möglicherweise noch einige Tage lang in den Abfrageergebnissen für die Anwendungstopologie angezeigt.
  • Für Sicherheits- und Compliance-Daten, die von Security Command Center bereitgestellt werden:
    • Die bereitgestellten Daten sind in der Vorschau verfügbar.
    • Daten sind nur für Projekte und Anwendungen in einer Google CloudOrganisation verfügbar.