Syntax von Suchanfragen

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

Durchsuchbare Felder und Ressourcen

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

Informationen zu den Feldern, die Sie in einer searchAllIamPolicies-Abfrage verwenden können, finden Sie unter IamPolicySearchResult-Felder.

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 beim genauen Textabgleich die folgenden Regeln:

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

• Bei einem Feld mit einem Listenwert gilt eine Übereinstimmung, wenn der Abfragewert mit einem der Elemente der Liste übereinstimmt.

• Bei Abfragewerten wird die Groß-/Kleinschreibung beachtet.

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

Teilweiser Textabgleich

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

ASSET_METADATA_FIELD:QUERY

Beispiel:

location:us-central1

Bei einer Suche mit dem Operator : werden der Abfragewert und die Werte der Asset-Metadatenfelder zum Vergleich in Tokens umgewandelt. Jedes Wort des Abfragewerts wird daraufhin geprüft, ob es in aufeinanderfolgender Reihenfolge im Wert des Felds der Asset-Metadaten enthalten ist. Bei der Verwendung von Teilübereinstimmungen wird die Groß-/Kleinschreibung bei den Abfragewerten nicht berücksichtigt.

Abfragewerte für Teilübereinstimmungen können Wortgruppen oder eine Kombination aus Wortgruppen sein und Platzhalter enthalten. In einer Abfrage können bis zu 10 Vergleiche mit maximal 2.048 Zeichen durchgeführt werden. Wenn Sie einen Anwendungsfall für längere Abfragen haben, wenden Sie sich an [e-mail].

Regeln für die Tokenisierung

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

• Voran- und nachgestellte Sonderzeichen werden entfernt.

• Zeichen, die nicht alphanumerisch ([a-zA-Z0-9]), Unterstriche (_) oder Kaufmännische Und-Zeichen (&) sind, werden als Trennzeichen behandelt.

Hier sind einige Beispiele zur Tokenisierung:

• us-central1 wird in [us,central1] tokenisiert.

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

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

• Compute %Instance% wird in [compute,instance] tokenisiert.

• $%^*-! wird in [] tokenisiert.

• compute*storage wird in [compute,storage] tokenisiert.

• compute&storage wird in [compute&storage] tokenisiert.

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

• instance/_my_vm_ wird in [instance,_my_vm_] tokenisiert.

Beispiele für exakte 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	Keine Übereinstimmung, da die Wortgruppe teilweise mit dem Wert des Felds übereinstimmt. Verwenden Sie stattdessen den Operator : für teilweise Übereinstimmungen.

Abfrage für Textabgleich erstellen

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

Wortgruppen

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

Die folgende Abfrage stimmt mit Assets überein, 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 aufeinanderfolgen. Das . wird ignoriert, da Satzzeichen als Trennzeichen behandelt werden.

Ein Asset, dessen Feld policy den Wert "[e-mail]" oder "[e-mail]" hat, stimmt nicht überein, da die Wörter alex und 2020 nicht in der angegebenen Reihenfolge enthalten sind.

Eine Wortgruppe erstellen

Beachten Sie beim Erstellen eines Ausdrucks die folgenden Regeln:

• Wenn die Wortgruppe nur Zeichen des ISO-Basis-Latein-Alphabets [a-zA-Z], Zahlen [0-9], einfache E-Mail- oder URL-Connectors [_-+.@/&] oder Platzhalter [*] enthält, muss sie nicht in doppelte Anführungszeichen gesetzt werden:

  policy:[e-mail]
  

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

  policy:"[e-mail]"
  

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

  location:"us central1"
  

• Wenn die Wortgruppe in doppelte Anführungszeichen eingeschlossen ist und auch ein doppeltes Anführungszeichen (") oder ein umgekehrter Schrägstrich (\) enthält, müssen Sie diese als \" oder \\ maskieren. Alternativ können Sie sie 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 zur Angabe eines Ausdrucks verwendet werden, mit einem Escapezeichen versehen:

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

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

Kombinationen

Suchwortgruppen können mit den großgeschriebenen logischen Operatoren AND oder OR kombiniert werden. Die Verwendung von AND ist optional, wenn Klammern verwendet werden. 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, muss nicht jedes Wort in einem einzelnen Element enthalten sein, wenn Sie AND verwenden. Wenn ein Metadatenfeld beispielsweise policy=["[e-mail]", "[e-mail]", "[e-mail]"] ist, wird bei der 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 enthält, oder Assets, deren Richtlinienfeld 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, die ein Richtlinienfeld mit alex und 2020 in aufeinanderfolgender Reihenfolge oder bola enthalten:

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

Beispiele für Kombinationen

Die folgenden Abfragen veranschaulichen verschiedene Kombinationen. Achten Sie auf die Platzierung der Klammern, um die Operatoren AND und OR zu trennen. Das Kombinieren von Operatoren in einem einzelnen Klammerpaar ist ungültig, 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 enthält 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 :Die Negation wird nur beim Durchsuchen von Ressourcen unterstützt, nicht bei IAM-Richtlinien.

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 nicht internal oder 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 überein, der ein Token enthält, das mit al beginnt (z. B. alex), und ein Token, das mit 20 beginnt (z. B. 2020).

• Wenn der gesamte Abfragewert für labels nur ein einzelnes * enthält, z. B. "labels.env:*", wird damit geprüft, ob das Attribut vorhanden ist. Cloud Asset Inventory prüft also, ob der Labelschlüssel env vorhanden ist. Nur das Feld labels unterstützt Existenzprüfungen.

• Wenn * in der Mitte einer Wortgruppe steht, 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 Abfrageparameter entspricht "compute storage".

Numerischer Vergleich und Zeitstempelvergleich

Verwenden Sie für den numerischen Vergleich und den Zeitstempelvergleich Vergleichsoperatoren mit der folgenden Syntax:

ASSET_METADATA_FIELD>=QUERY

Folgende Vergleichsoperatoren sind verfügbar:

• =: gleich

• >: größer als

• >=: Größer als oder gleich

• <: Weniger als

• <=: Kleiner als oder gleich

Wenn Sie Zeitstempel wie die in den Asset-Metadatenfeldern createTime und updateTime gespeicherten vergleichen möchten, verwenden Sie eine signierte 64-Bit-Ganzzahl (den Epochenzeitstempel in Sekunden) oder einen UTC+0-Datum-/Uhrzeit-String in einem der folgenden Formate:

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

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

Beispiele für Datetime

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"