検索クエリの構文

アセットを検索するときに、アセットメタデータフィールド、演算子、値で構成されるクエリを指定して、検索結果をフィルタできます。

検索可能フィールドとリソース

searchAllResources クエリで使用できるフィールドについては、ResourceSearchResult フィールドをご覧ください。

searchAllIamPolicies クエリで使用できるフィールドについては、IamPolicySearchResult フィールドをご覧ください。

検索可能なリソースについては、リソースタイプをご覧ください。

テキストマッチング

テキスト一致を検索する場合は、アセットメタデータフィールドを完全一致または部分一致で検索できます。

テキストの完全一致

テキストの完全一致の場合は、次の構文で =（等価）演算子を使用します。

ASSET_METADATA_FIELD=QUERY

次に例を示します。

location=us-central1-a

完全一致を実行する際は、次のルールに注意してください。

クエリが true になるには、クエリ値がアセットメタデータフィールドの値と完全に一致している必要があります。
リスト値を持つフィールドの場合、クエリ値がリストの要素のいずれかと一致すると、一致と見なされます。
クエリ値では大文字と小文字が区別されます。
完全一致のクエリ値はフレーズのように扱われますが、ワイルドカードを含めることはできません。

テキストの部分一致

テキストの部分一致の場合は、次の構文で :（has）演算子を使用します。

ASSET_METADATA_FIELD:QUERY

次に例を示します。

location:us-central1

: 演算子を使用して検索を実行すると、クエリ値とアセットメタデータフィールド値は比較のためにトークンに変換されます。クエリ値の各単語が、アセットメタデータフィールドの値に連続して存在するかどうかがチェックされます。部分一致を使用する場合、クエリ値は大文字と小文字を区別しません。

部分一致のクエリ値には、フレーズまたはフレーズの組み合わせを使用できます。また、ワイルドカードを含めることもできます。クエリで実行できる比較は 10 個までで、最大文字数は 2, 048 文字です。より長いクエリのユースケースをお持ちの場合は、gcp-asset-inventory-and-search-feedback@googlegroups.com までお問い合わせください。

トークン化ルール

部分一致テキストマッチングのトークン化ルールは次のとおりです。

先頭と末尾の特殊文字は削除されます。
英数字（[a-zA-Z0-9]）、アンダースコア（_）、アンパサンド（&）以外の文字は、区切り文字として扱われます。

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

us-central1 は [us,central1] にトークン化されます。
alex-2020@EXAMPLE.com は [alex,2020,example,com] にトークン化されます。
google.com/cloud は [google,com,cloud] にトークン化されます。
Compute %Instance% は [compute,instance] にトークン化されます。
$%^*-! は [] にトークン化されます。
compute*storage は [compute,storage] にトークン化されます。
compute&storage は [compute&storage] にトークン化されます。
ALEX_test@example.com は [alex_test,example,com] にトークン化されます。
instance/_my_vm_ は [instance,_my_vm_] にトークン化されます。

完全一致と部分一致の例

location フィールドの値が us-central1-a のアセットは、次のクエリに一致します。

クエリ	一致の理由
location=us-central1-a	フレーズ `us-central1-a` がフィールドの値と完全に同じであるため、一致しています。
location:US-Central1-A	句読点は区切り文字として扱われ、クエリ値では大文字と小文字が区別されないため、一致します。
location:"us central1 a"	フレーズ `"us central1 a"` 内の単語がフィールド値と連続して一致しているため、一致します。
location:(central1 us a)	組み合わせ `(central1 us a)` 内の単語が、フィールド値内の単語と任意の順序で一致するため、一致します。
location:(a "us central1")	組み合わせ内のフレーズ（`a` と `"us central1"`）が、フィールド値内の単語と任意の順序で一致するため、一致します。`"us central1"` はフレーズであるため、これらの単語は連続した順序で照合する必要があります。
location:us-central*	ワイルドカード `*` が接頭辞の一致に使用されているため、一致します。

location フィールドの値が us-central1-a のアセットは、次のクエリと一致しません。

クエリ	一致しない理由
location=US-central1-a	フレーズの大文字と小文字は区別されるため、一致しません。大文字と小文字を区別しない一致には、代わりに（`:`）演算子を使用します。
location=us-central1	フレーズがフィールドの値と部分的に一致しているため、一致しません。部分一致には、代わりに `:` 演算子を使用します。

テキスト一致クエリを作成する

クエリ値は、フレーズ、組み合わせ、否定、ワイルドカードで構成できます。

フレーズ

フレーズは、順序に従って照合される 1 つ以上の単語です。順序を指定せずに単語を照合するには、代わりに組み合わせを使用します。

次のクエリは、policy フィールドに単語 alex と単語 2020 が連続して含まれているアセットに一致します。

policy:"alex 2020"

policy フィールドの値が "alex.2020@example.com" のアセットは、alex と 2020 の単語が連続しているため、クエリと一致します。句読点は区切り文字として扱われるため、. は無視されます。

policy フィールドの値が "2020.alex@example.com" または "alex.us.2020@example.com" のアセットは一致しません。これは、alex と 2020 が連続していないためです。

フレーズを作成する

フレーズを作成する際は、次のルールに注意してください。

フレーズに ISO 基本ラテン文字 [a-zA-Z]、数字 [0-9]、基本的なメールアドレスまたは URL のコネクタ [_-+.@/&]、ワイルドカード [*] のみが含まれている場合、フレーズを二重引用符で囲む必要はありません。
```
policy:alex.2020@example.com
```
ただし、二重引用符で囲む方法は引き続き機能し、動作も同じです。
```
policy:"alex.2020@example.com"
```
フレーズにスペースやその他の特殊文字が含まれている場合は、二重引用符で囲む必要があります。
```
location:"us central1"
```
フレーズが二重引用符で囲まれていて、二重引用符（"）またはバックスラッシュ（\）が含まれている場合は、\" または \\ としてエスケープする必要があります。検索の際に英数字以外の文字が区切り文字として扱われるため、半角スペース 1 個に置き換えることもできます。次のクエリは同じ方法で処理されます。
```
description:"One of \"those\" descriptions."
description:"One of those descriptions."
```
gcloud CLI または REST API を使用する場合は、フレーズを示すダブルクォーテーションをエスケープする必要があります。
```
--query="location:(a \"us central1\")"
```
```
"query": "location:(a \"us central1\")"
```

組み合わせ

検索フレーズは、大文字の論理演算子 AND または OR を使用して組み合わせることができます。括弧を使用する場合、AND を含めるかどうかは任意です。たとえば、次のクエリは同じ方法で処理されます。

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

アセットに値のリストを含むメタデータフィールドが含まれている場合、AND の組み合わせで、すべての単語が 1 つの要素に収まるとは限りません。たとえば、メタデータフィールドが policy=["alex@example.com", "bola@example.com", "charlie@example.com"] の場合、policy:(alex charlie) で検索すると一致します。これは、alex@example.com に alex が含まれ、charlie@example.com に charlie が含まれているためです。

かっこを使用して組み合わせの種類をグループ化できます。次の例では、alex と charlie が任意の順序で含まれるポリシーフィールドを持つアセット、または bola を含むポリシーフィールドを持つアセットを返します。

policy:((alex charlie) OR bola)

組み合わせの中にフレーズを使用すると、複数の単語を連続して照合できます。次の例では、alex と 2020 が連続して含まれているポリシーフィールド、または bola を含むアセットを返します。

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

組み合わせの例

次のクエリは、さまざまな組み合わせを示しています。AND 演算子と OR 演算子を区切る括弧の配置に注意してください。1 つのかっこ内で演算子を組み合わせることはできません（例: policy:(alex charlie OR bola)）。

クエリ	説明
policy:(alex charlie)	`policy` フィールドに `alex` と `charlie` の両方を含むアセットを返します。
policy:(alex OR charlie)	`policy` フィールドに `alex` または `charlie` を含むアセットを返します。
policy:((alex charlie) OR bola)	`policy` フィールドに `alex` と `charlie` の両方を含むか、`bola` という単語を含むアセットを返します。
policy:(alex charlie) OR name:bola	`policy` フィールドに `alex` と `charlie` が含まれるか、`name` フィールドに `bola` が含まれるアセットを返します。

否定

検索クエリは、大文字の NOT 演算子を使用して否定できます。丸括弧がサポートされていますが、必須ではありません。

否定の例

state フィールドに running という単語が含まれないアセットを返します。
```
NOT state:running
```
policy フィールドに alex も charlie も含まないアセットを返します。
```
NOT policy:(alex OR charlie)
```
networkTags フィールドに internal または private を含まないアセットを返します。
```
NOT (networkTags:internal OR networkTags:private)
```

ワイルドカード

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

* がフレーズの末尾にある場合、トークンプレフィックスマッチとして扱われます。たとえば、"al 20*" は (al* 20*) と同じです。接頭辞の順序は関係ありません。

フレーズ "al 20*" は、al で始まるトークン（alex など）と 20 で始まるトークン（2020 など）を含むフィールド値に一致します。
labels の場合、クエリ値全体に * が 1 つだけ含まれている場合（"labels.env:*" など）、存在チェックを表します。つまり、Cloud Asset Inventory はラベルキー env が存在するかどうかを確認します。存在チェックをサポートするのは labels フィールドのみです。
* がフレーズの途中に存在する（例: "compute*storage"）場合は、トークン化区切り文字として扱われます。このクエリ値は "compute storage" と同じです。
* がフレーズの先頭と末尾に存在する（例: "*compute storage*"）場合は、トークン化区切り文字として扱われます。このクエリ値は "compute storage" と同じです。

数値とタイムスタンプの比較

数値とタイムスタンプの比較には、次の構文で比較演算子を使用します。

ASSET_METADATA_FIELD>=QUERY

使用できる比較演算子は次のとおりです。

=: 等しい
>: 大きい
>=: 大きいまたは同じ
<: 小さい
<=: 小さいまたは同じ

createTime アセットメタデータフィールドや updateTime アセットメタデータフィールドに保存されているタイムスタンプと比較するには、64 ビット符号付き整数（秒単位のエポックタイムスタンプ）または UTC+0 日時文字列（次のいずれかの形式）を使用します。

2021-01-01（YYYY/MM/DD）
"2021-01-01T00:00:00" ("YYYY-MM-DDThh:mm:ss")

日時の例

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"