Syntax von Suchanfragen

Wenn Sie nach Assets suchen, können Sie die Suchergebnisse filtern, indem Sie eine Suchanfrage mit einem Asset-Metadatenfeld, einem Operator und einem Wert angeben.

Suchbare Felder und Ressourcen

Informationen zu den Feldern, die Sie in einer searchAllResources-Abfrage verwenden können, finden Sie unter Felder für ResourceSearchResult.

Informationen zu den Feldern, die Sie in einer searchAllIamPolicies-Abfrage verwenden können, finden Sie unter Felder für IAM-Richtliniensuchergebnisse.

Informationen zu den Ressourcen, nach denen Sie suchen können, finden Sie unter Ressourcentypen.

Textabgleich

Bei der Suche nach einer Textübereinstimmung können Sie ein Asset-Metadatenfeld genau oder teilweise abgleichen.

Genaue Textübereinstimmung

Verwenden Sie für eine genaue Textübereinstimmung den Operator = (gleich) mit der folgenden Syntax:

ASSET_METADATA_FIELD=QUERY

Beispiel:

location=us-central1-a

Beachten Sie bei der Verwendung der genauen Übereinstimmung die folgenden Regeln:

• Damit die Abfrage wahr ist, muss der Abfragewert genau mit dem Wert des Asset-Metadatenfelds übereinstimmen.

• Wenn der Abfragewert bei einem Feld mit einem Listenwert mit einem der Elemente der Liste übereinstimmt, wird dies als Übereinstimmung betrachtet.

• Bei Abfragewerten wird die Groß- und Kleinschreibung berücksichtigt.

• Ein Abfragewert für die genaue Übereinstimmung wird wie eine Wortgruppe behandelt, darf aber keine Wildcards enthalten.

Teilweise Textübereinstimmung

Verwenden Sie für eine teilweise Textübereinstimmung den Operator : (hat) mit der folgenden Syntax:

ASSET_METADATA_FIELD:QUERY

Beispiel:

location:us-central1

Wenn Sie eine Suche mit dem Operator : ausführen, werden der Abfragewert und die Werte der Asset-Metadatenfelder zum Vergleich in Tokens umgewandelt. Es wird geprüft, ob jedes Wort des Abfragewerts in aufeinanderfolgender Reihenfolge im Wert des Felds der Asset-Metadaten enthalten ist. Bei der Verwendung von Teilübereinstimmungen wird die Groß- und Kleinschreibung der Abfragewerte ignoriert.

Abfragewerte für die teilweise Übereinstimmung können Wortgruppen oder eine Kombination von Wortgruppen sein und Platzhalter enthalten. In einer Abfrage können bis zu zehn Vergleiche mit maximal 2.048 Zeichen durchgeführt werden. Wenn Sie einen Anwendungsfall für längere Abfragen haben, kontaktieren Sie uns unter [e-mail].

Tokenisierungsregeln

Die Tokenisierungsregeln für die teilweise Textübereinstimmung sind:

• Voran- und nachgestellte Sonderzeichen werden entfernt.

• Nicht alphanumerische Zeichen ([a-zA-Z0-9]), Unterstriche (_) oder Ampersands (&) werden als Trennzeichen behandelt.

Hier sind einige Beispiele zur Tokenisierung:

• us-central1 wird zu [us,central1] tokenisiert

• [e-mail] wird zu [alex,2020,example,com] tokenisiert

• google.com/cloud wird zu [google,com,cloud] tokenisiert

• Compute %Instance% wird zu [compute,instance] tokenisiert

• $%^*-! wird zu [] tokenisiert

• compute*storage wird zu [compute,storage] tokenisiert

• compute&storage wird zu [compute&storage] tokenisiert

• [e-mail] wird zu [alex_test,example,com] tokenisiert

• instance/_my_vm_ wird zu [instance,_my_vm_] tokenisiert

Beispiele für genaue und teilweise Textübereinstimmungen

Ein Asset, dessen Feld location den Wert us-central1-a enthält, stimmt mit den folgenden Abfragen überein.

Abfrage	Grund für die Übereinstimmung
location=us-central1-a	Übereinstimmung, da die Wortgruppe us-central1-a genau mit dem Wert des Felds übereinstimmt.
location:US-Central1-A	Übereinstimmung, da Satzzeichen als Trennzeichen behandelt werden und die Groß-/Kleinschreibung beim Abfragewert nicht berücksichtigt wird.
location:"us central1 a"	Übereinstimmung, da die Wörter in der Wortgruppe "us central1 a" in der richtigen Reihenfolge mit dem Feldwert übereinstimmen.
location:(central1 us a)	Übereinstimmung, da die Wörter in der Kombination (central1 us a) in beliebiger Reihenfolge mit den Wörtern im Feldwert übereinstimmen.
location:(a "us central1")	Übereinstimmung, da die Wortgruppen in der Kombination, a und "us central1", in beliebiger Reihenfolge mit den Wörtern im Feldwert übereinstimmen. Da "us central1" eine Wortgruppe ist, müssen diese Wörter in der richtigen Reihenfolge abgeglichen werden.
location:us-central*	Übereinstimmung, da der Platzhalter * für eine Präfixübereinstimmung verwendet wird.

Ein Asset, dessen Feld location den Wert us-central1-a enthält, stimmt NICHT mit den folgenden Abfragen überein:

Abfrage	Grund für die fehlende Übereinstimmung
location=US-central1-a	Keine Übereinstimmung, da bei der Wortgruppe die Groß-/Kleinschreibung berücksichtigt wird. Verwenden Sie stattdessen den Operator :, wenn die Groß-/Kleinschreibung nicht berücksichtigt werden soll.
location=us-central1	Übereinstimmung, da die Wortgruppe teilweise mit dem Wert des Felds übereinstimmt. Verwenden Sie stattdessen den Operator :, um eine teilweise Übereinstimmung zu finden.

Abfrage mit Textübereinstimmung erstellen

Ein Abfragewert kann aus Wortgruppen, Kombinationen, Negationen und Platzhaltern bestehen.

Wortgruppen

Eine Wortgruppe besteht aus einem oder mehreren Wörtern, die in der richtigen Reihenfolge abgeglichen werden. Wenn Sie Wörter ohne Berücksichtigung der Reihenfolge abgleichen möchten, verwenden Sie stattdessen Kombinationen.

Mit der folgenden Abfrage werden Assets gefunden, deren Feld policy die Wörter alex und 2020 in der richtigen Reihenfolge enthält:

policy:"alex 2020"

Ein Asset, dessen Feld policy den Wert "[e-mail]" enthält, stimmt mit der Abfrage überein, da die Wörter alex und 2020 in der richtigen Reihenfolge und Abfolge enthalten sind. Das Zeichen . wird ignoriert, da Satzzeichen als Trennzeichen behandelt werden.

Bei einem Asset, dessen Feld policy den Wert "[e-mail]" oder "[e-mail]" hat, besteht keine Übereinstimmung, da die Wörter alex und 2020 nicht in der richtigen Reihenfolge sind.

Wortgruppe erstellen

Beachten Sie beim Erstellen einer Wortgruppe die folgenden Regeln:

• Wenn die Wortgruppe nur Zeichen des lateinischen Grundalphabets nach ISO [a-zA-Z], Zahlen [0-9], einfache E-Mail- oder URL-Connectors [_-+.@/&] oder Platzhalter [*] enthält, müssen Sie sie nicht in doppelte Anführungszeichen setzen:

  policy:[e-mail]
  

  Das Einschließen in doppelte Anführungszeichen funktioniert jedoch weiterhin und verhält sich gleich:

  policy:"[e-mail]"
  

• Wenn der Ausdruck Leerzeichen oder andere Sonderzeichen enthält, muss er in doppelte Anführungszeichen gesetzt werden:

  location:"us central1"
  

• Wenn die Wortgruppe in doppelte Anführungszeichen gesetzt ist und auch ein doppeltes Anführungszeichen (") oder einen umgekehrten Schrägstrich (\) enthält, müssen Sie diese Zeichen mit \" oder \\ maskieren. Sie können sie auch durch ein einzelnes Leerzeichen ersetzen, da nicht alphanumerische Zeichen bei der Suche als Trennzeichen behandelt werden. Die folgenden Abfragen werden gleich behandelt:

  description:"One of \"those\" descriptions."
  description:"One of those descriptions."
  

• Wenn Sie die gcloud CLI oder die REST API verwenden, müssen Sie die doppelten Anführungszeichen, die einen Ausdruck kennzeichnen, mit einem Escape-Zeichen versehen:

  --query="location:(a \"us central1\")"
  

  "query": "location:(a \"us central1\")"
  

Kombinationen

Suchwortgruppen können mit den logischen Operatoren AND oder OR kombiniert werden. Die Verwendung von AND ist bei Klammern optional. Die folgenden Abfragen werden beispielsweise gleich behandelt:

policy:(alex charlie)
policy:(alex AND charlie)

Wenn ein Asset ein Metadatenfeld mit einer Liste von Werten enthält, ist bei einer AND-Kombination nicht garantiert, dass sich alle Wörter in einem einzigen Element befinden. Wenn ein Metadatenfeld beispielsweise policy=["[e-mail]", "[e-mail]", "[e-mail]"] ist, wird bei einer Suche mit policy:(alex charlie) eine Übereinstimmung gefunden, da [e-mail] alex und [e-mail] charlie enthält.

Sie können Kombinationstypen mit Klammern gruppieren. Im folgenden Beispiel werden Assets zurückgegeben, deren Richtlinienfeld alex und charlie in beliebiger Reihenfolge oder bola enthält.

policy:((alex charlie) OR bola)

Sie können eine Wortgruppe in einer Kombination verwenden, um mehrere Wörter in aufeinanderfolgender Reihenfolge abzugleichen. Im folgenden Beispiel werden Assets zurückgegeben, deren Richtlinienfeld alex und 2020 in aufeinanderfolgender Reihenfolge oder bola enthält:

policy:(("alex 2020") OR bola)

Beispiele für Kombinationen

Die folgenden Abfragen veranschaulichen verschiedene Kombinationen. Beachten Sie die Platzierung der Klammern, um AND- und OR-Operatoren voneinander zu trennen. Die Kombination von Operatoren innerhalb einer einzigen Klammer ist unzulässig, z. B.: policy:(alex charlie OR bola).

Abfrage	Beschreibung
policy:(alex charlie)	Gibt Assets zurück, deren Feld policy sowohl alex als auch charlie enthält.
policy:(alex OR charlie)	Gibt Assets zurück, deren Feld policy entweder alex oder charlie enthält.
policy:((alex charlie) OR bola)	Gibt Assets zurück, deren Feld policy sowohl alex als auch charlie oder das Wort bola enthält.
policy:(alex charlie) OR name:bola	Gibt Assets zurück, deren Feld policy alex und charlie oder deren Feld name bola enthält.

Negation

Suchanfragen können mit dem Operator NOT in Großbuchstaben negiert werden. Klammern werden unterstützt, sind aber nicht erforderlich.

Hinweis: Negation wird nur beim Durchsuchen von Ressourcen, nicht bei IAM-Richtlinien unterstützt.

Beispiele für Negationen

• Gibt Assets zurück, deren Feld state nicht das Wort running enthält.

  NOT state:running
  

• Gibt Assets zurück, deren Feld policy weder alex noch charlie enthält.

  NOT policy:(alex OR charlie)
  

• Gibt Assets zurück, deren Feld networkTags weder internal noch private enthält.

  NOT (networkTags:internal OR networkTags:private)
  

Platzhalter

Sternchen (*) können in einer Wortgruppe als Platzhalterzeichen verwendet werden. Je nach Position kann ein Sternchen unterschiedliche Bedeutungen haben.

• Wenn * am Ende einer Wortgruppe steht, wird es als Token-Präfixübereinstimmung behandelt. "al 20*" entspricht beispielsweise (al* 20*). Die Reihenfolge der Präfixe spielt keine Rolle.

  Der Ausdruck "al 20*" stimmt mit einem Feldwert mit einem Token überein, das mit al beginnt (z. B. alex), und einem Token, das mit 20 beginnt (z. B. 2020).

• Wenn der gesamte Abfragewert für labels nur einen einzelnen * enthält, z. B. "labels.env:*", handelt es sich um eine Existenzprüfung. Cloud Asset Inventory prüft also, ob der Labelschlüssel env vorhanden ist. Nur das Feld labels unterstützt Existenzprüfungen.

• Wenn sich * in der Mitte einer Wortgruppe befindet, z. B. "compute*storage", wird es als Tokenisierungstrennzeichen behandelt. Dieser Abfragewert entspricht "compute storage".

• Wenn * sowohl am Anfang als auch am Ende einer Wortgruppe steht, z. B. "*compute storage*", wird es als Tokenisierungstrennzeichen verwendet. Dieser Abfragewert entspricht "compute storage".

Vergleich von Zahlen und Zeitstempeln

Verwenden Sie für den Vergleich von Zahlen und Zeitstempeln Vergleichsoperatoren mit der folgenden Syntax:

ASSET_METADATA_FIELD>=QUERY

Folgende Vergleichsoperatoren sind verfügbar:

• =: gleich

• >: größer als

• >=: Größer als oder gleich

• <: kleiner als

• <=: Kleiner als oder gleich

Wenn du Zeitstempel vergleichen möchtest, z. B. die in den Asset-Metadatenfeldern createTime und updateTime gespeicherten, verwende eine signierte 64-Bit-Ganzzahl (den Epochenzeitstempel in Sekunden) oder einen Datums-/Uhrzeit-String in UTC+0 in einem der folgenden Formate:

• 2021-01-01 (JJJJ-MM-TT)

• "2021-01-01T00:00:00" ("YYYY-MM-DDThh:mm:ss")

Beispiele für Datumsangaben und Uhrzeiten

Ein Asset, dessen Feld createTime den Wert 1609459200 (Epochen-Zeitstempel von 2021-01-01T00:00:00) enthält, stimmt mit den folgenden Abfragen überein:

createTime=1609459200
createTime=2021-01-01
createTime="2021-01-01T00:00:00"

createTime>1500000000
createTime>2020-01-01
createTime>"2020-01-01T00:00:00"

createTime>=1609459200
createTime>=2021-01-01
createTime>="2021-01-01T00:00:00"

createTime<1700000000
createTime<2022-01-01
createTime<"2022-01-01T00:00:00"

createTime<=1609459200
createTime<=2021-01-01
createTime<="2021-01-01T00:00:00"