クエリ構文

アセットを検索するには、FIELD、演算子、QUERY を指定して、検索結果をフィルタリングします。

テキスト完全一致: 等価演算子（=）

FIELD=QUERY

クエリの例: policy=[e-mail]。

equals（=）演算子は、QUERY がアセット メタデータ FIELD の値と完全に一致することを確認します。大文字と小文字が区別されます。繰り返しフィールドの場合、QUERY がフィールドの値のいずれかと一致すると、アセットは一致と見なされます。サポートされている FIELD 名は、クエリがリソース検索か、Identity and Access Management（IAM）ポリシー検索かによって異なります。QUERY はフレーズですが、ワイルドカードは使用できません。

テキスト部分一致: コロン演算子（:）

FIELD:QUERY

クエリの例: policy:amy.2020@gmail。

検索を実行すると、QUERY と指定したアセット メタデータ FIELD の値が比較されます。クエリとアセット メタデータ フィールドは比較のために一連の単語（すなわちトークン）に変換されます。これは、次のようにして行われます。

• 先頭または末尾の特殊文字を削除し、特殊文字を区切り文字として扱うことにより検索値をトークン化する。トークン化特殊文字は、英数字 [a-zA-Z0-9]、アンダースコア [_]、アンパサンド [&] のいずれでもない文字です。

• Unicode の大文字小文字変換を行って、文字の大文字小文字の区別が無視されるようにします。

以下にトークン化の例を示します。

• "[e-mail]" は [amy,2020,gmail,com] にトークン化されます。

• "google.com/cloud" は [google,com,cloud] にトークン化されます。

• "Compute %Instance%" は [compute,instance] にトークン化されます。

• "$%^*-!" は [] にトークン化されます。

• "" は [] にトークン化されます。

• "compute*storage" は [compute,storage] にトークン化されます。

• "compute&storage" は [compute&storage] にトークン化されます。

• "[e-mail]" は [bob_test,gmail,com] にトークン化されます。

• "instance/_my_vm_" は [instance,_my_vm_] にトークン化されます。

has（:）演算子は、QUERY の各単語がアセット メタデータ フィールドの値内に存在するかを確認します。単語の順序と連続性も確認します。サポートされる FIELD は、リソース検索か IAM ポリシー検索かによって異なることがあります。QUERY は、フレーズまたは複数フレーズの組み合わせです。

注: クエリには、上記の形式に従って複数の比較を含めることができます。詳細については、組み合わせをご覧ください。比較の数は 10 組、2048 文字に限定されます。これより長いクエリを使用する場合は、[e-mail] までお問い合わせください。

例

たとえば、policy フィールドの値が [e-mail] のアセットは、次のクエリに一致します。

• フレーズがフィールドの値と完全に同じであるため、一致しています。

policy=[e-mail]

• 句読点は区切り文字として扱われ、クエリでは大文字と小文字が区別されないため、一致します。

policy:[e-mail]

• フレーズ内の単語が順に照合されるため、一致します。なお、"amy 2020 gmail" はフレーズです。単語を順につなげて連続的に照合します。

policy:"amy 2020 gmail"

• 単語の組み合わせは任意の順序で出現するため、一致します。なお、(gmail 2020 amy) は組み合わせです。単語必ずしも順番に照合されません。

policy:(gmail 2020 amy)

• フレーズ内の単語が順番どおりに一致し、組み合わせ内の単語が順番どおり出現するため、一致します。なお、"amy 2020" はフレーズです。単語を順につなげて連続的に照合します。(gmail "amy 2020") は組み合わせです。gmail と "amy 2020" は必ずしも順序どおりに照合されません。

policy:(gmail "amy 2020")

• * が接頭辞の一致を示すためにフレーズ内で使用できるため、一致します。

policy:amy-20*

policy フィールドの値が "[e-mail]" のアセットは、次のクエリと一致しません。

• フレーズの大文字と小文字は区別されるため、一致しません。大文字と小文字を区別しない一致には、代わりに has（:）演算子を使用します。

policy=[e-mail]

• フレーズがフィールドの値と部分的に一致しているため、一致しません。部分一致には、代わりに has（:）演算子を使用します。

policy=amy.2020@gmail

数値一致: 比較演算子（=、>、>=、<、<=）

FIELD=QUERY

FIELD>QUERY

FIELD>=QUERY

FIELD<QUERY

FIELD<=QUERY

比較演算子は、QUERY とアセット メタデータ FIELD の値との比較結果が true であるかどうかを確認します。

サポートされている FIELD 名には createTime と updateTime があります。

タイムスタンプ フィールド（createTime と updateTime）の場合、QUERY は 64 ビット符号付き整数です。これは秒単位のエポック タイムスタンプ、または以下のいずれかの形式の日時文字列（タイムゾーンは UTC）を表します。

• YYYY-MM-DD: 2021-01-01（引用符は省略可能）

• "YYYY-MM-DDThh:mm:ss": "2021-01-01T00:00:00"（引用符は必須）

例

たとえば、createTime フィールドの値が 1609459200（2021-01-01T00:00:00 のエポック タイムスタンプ）であるアセットは、次のクエリに一致します。

等しい

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"

フレーズ

フレーズは、二重引用符（"）で囲まれた 1 つ以上の単語です。フレーズでは、単語の順序が重要となります。フレーズ内の単語は、順序どおり、連続的に一致する必要があります。なお、順序を指定せずに複数の単語を照合するには、組み合わせを使用する必要があります（field:(word1 word2 word3) など）。

注: フレーズに英字 [a-zA-Z]、数字 [0-9]、基本的なメールアドレスまたは URL のコネクタ [_-+.@/&]、ワイルドカード [*] が含まれる場合、フレーズを二重引用符で囲む必要はありません。引用符で囲まれたフレーズに " または \ が含まれている場合は、\" または \\ としてエスケープする必要があります。検索の際に英数字以外の文字が区切り文字として扱われるため、" または \ を１つの半角スペースに置き換えることもできます。

次の式は同じ内容を表します。

policy:amy
policy:"amy"

policy:[e-mail]
policy:"[e-mail]"

name://cloudresourcemanager.googleapis.com/projects/projects/foo-bar
name:"//cloudresourcemanager.googleapis.com/projects/projects/foo-bar"

次のフレーズは、引用符で囲む必要があります。

name:"my instance"

policy:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

例: フレーズ

• policy フィールドに単語 amy および単語 2020 が含まれているアセットを順番に続けて返します。

  policy:"amy 2020"
  

• policy フィールドの値が "[e-mail]" であるアセットがある場合は、上記のクエリと一致します。

• policy フィールド値が "[e-mail]" であるアセットがある場合、単語の順序が一致しないため、上記のクエリと一致しません。

• policy フィールド値が "[e-mail]" であるアセットがある場合、単語は連続して一致していないため、上記のクエリと一致しません。

組み合わせ

検索フレーズは、AND または OR を使用して組み合わせることができます。括弧は組み合わせをグループ化するために使用します。

注: 演算子 AND と OR は大文字にする必要があります。クエリで AND と OR の両方が使用されている場合、括弧を適切に使用して組み合わせをグループ化する必要があります。

例: 組み合わせ

• policy フィールドに単語 amy と単語 john の両方が含まれるアセットを、順序を指定せずに返します。AND は組み合わせでは省略可能です。なお、複数の単語を順番どおり照合するには、フレーズを使用する必要があります（例: field:"word1 word2 word3"）。

  owner:(amy john)
  

  注: アセットに値のリストを含むフィールド（policy=["[e-mail]", "[e-mail]", "[e-mail]"] など）が存在する場合は、policy:(amy john) で検索すると、[e-mail] に amy が含まれ、[e-mail] に単語 john が含まれるため、アセットと一致します。このフィールドに単語 amy と単語 john の両方を含む 1 つの要素（[e-mail] など）が含まれるとは限りません。

• policy フィールドに amy または john のいずれかの単語を含むアセットを返します。

  policy:(amy OR john)
  

• policy フィールドに単語 amy と john の両方または単語 bob を含むアセットを返します。

  policy:((amy john) OR bob)
  

  注: 組み合わせをグループ化するには、括弧を適切に使用する必要があります。上記のクエリでは、括弧を省略できません。policy:(amy john OR bob) というクエリは正しい形式ではありません。

• Return assets whose policy フィールドに単語 amy と単語 john が含まれるか、name フィールドに単語 bob が含まれるアセットを返します。

  policy:(amy john) OR name:bob
  

検索フィルタを無効にする

検索フィルタは、NOT 演算子を使用して無効にできます。丸括弧がサポートされていますが、必須ではありません。

注: NOT 演算子は大文字にする必要があります。否定はリソースを検索する場合にのみサポートされます。

例: 検索フィルタを無効にする

• state フィールドに ACTIVE という単語が含まれないアセットを返します。

  NOT state:ACTIVE
  

• policy フィールドに amy、john のいずれの単語も含まないアセットを返します。

  NOT policy:(amy OR john)
  

• networkTags フィールドに単語 internal または private を含まないアセットを返します。

  NOT (networkTags:internal OR networkTags:private)
  

ワイルドカード

アスタリスク（*）は、ワイルドカード文字としてフレーズで使用できます。位置によっては、異なる意味を持つこともあります。

• フレーズの末尾に存在する（"am 20*" など）の場合は、トークン プレフィックス マッチ指標です。このクエリは (am* 20*) と同じです。これは、「am」で始まるトークン（「amy」など）と「20」で始まるトークン（「2021」など）を含むフィールドと一致します。接頭辞の順序は関係ありません。

• フレーズ全体に 1 つの * のみが含まれている（例: "labels.env:*"）場合は、存在チェックを実行します。指定されたラベルキー「env」が存在するかどうかを確認します。他のフィールドはサポートされていません。

• フレーズの途中に存在する（例: "compute*storage"）場合は、トークン化区切り文字として扱われます。このクエリは「compute storage」と同等です。

• フレーズの先頭と末尾に存在する（例: "*compute storage*"）場合は、トークン化区切り文字として扱われます。このクエリは「compute storage」と同等です。

例: トークンの接頭辞の一致

• policy フィールドに am で始まる単語を含むアセットを返します。

  policy:am*
  

• "amy" と "20" を接頭辞とする 2 つの単語を policy フィールドに持つアセットを返します。

  policy:"amy 20*"
  
  policy:"20 amy*"
  

• policy フィールド値が "[e-mail]" のアセットの場合、上記のクエリは両方とも一致します。トークン化した後、"amy" と "20" の両方が接頭辞になります。なお、クエリ文字列 "amy 20*" は "amy 20" とは異なります。後者の場合、20 は接頭辞以外の単語全体である必要があります。

例: ラベルキーの存在

labels に「env」というキーがあり、任意の値（空の値や値なしを含む）を持つアセットを返します。

labels.env:*