此页面由 Cloud Translation API 翻译。

搜索查询语法

搜索资源时，您可以通过指定由资源元数据字段、运算符和值组成的查询来过滤搜索结果。

可搜索的字段和资源

如需了解可在 searchAllResources 查询中使用的字段，请参阅ResourceSearchResult 字段。

如需了解可在 searchAllIamPolicies 查询中使用的字段，请参阅 IamPolicySearchResult 字段。

如需了解可搜索的资源，请参阅资源类型。

文本匹配

搜索匹配的文本时，您可以完全或部分匹配资产元数据字段。

完全匹配文本

如需进行完全文本匹配，请使用 =（等于）运算符，语法如下：

ASSET_METADATA_FIELD=QUERY

例如：

location=us-central1-a

执行完全文本匹配时，请注意以下规则：

若要使查询为 true，查询值必须与相应资产元数据字段的值完全一致。
对于具有列表值的字段，如果查询值与列表的某个元素匹配，则视为匹配。
查询值区分大小写。
完全匹配查询值会被视为短语，但不能包含通配符。

部分文本匹配

如需进行部分文本匹配，请使用 :（包含）运算符，语法如下：

ASSET_METADATA_FIELD:QUERY

例如：

location:us-central1

使用 : 运算符执行搜索时，系统会将查询值和资源元数据字段值转换为词法单元以进行比较。系统会检查查询值的每个字词是否按顺序连续出现在资产元数据字段的值中。使用部分匹配时，查询值不区分大小写。

部分匹配查询值可以是短语或短语组合，并且可以包含通配符。一个查询最多可以进行 10 次比较，最多包含 2048 个字符。如果您有更长查询的用例，请通过 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	不匹配，因为词组部分与字段的值匹配。请改用 `:` 运算符进行部分匹配。

构建文本匹配查询

查询值可以由短语、组合、否定和通配符组成。

短语

词组是指按顺序匹配的一个或多个字词。如需不考虑顺序地匹配字词，请改用组合。

以下查询会匹配 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]、基本电子邮件或网址连接符 [_-+.@/&] 或通配符 [*]，则无需将其用双引号引起：
```
policy:alex.2020@example.com
```
不过，用英文双引号括起来仍然有效，并且行为方式相同：
```
policy:"alex.2020@example.com"
```
如果短语包含空格或其他特殊字符，则必须用英文双引号括起来：
```
location:"us central1"
```
如果词组用英文双引号括起来，并且还包含英文双引号 (") 或反斜杠 (\)，您必须将它们转义为 \" 或 \\。或者，您也可以将它们替换为单个空格，因为在执行搜索时，非字母数字字符会被视为分隔符。以下查询的处理方式相同：
```
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 组合并不保证所有字词都必须位于单个元素中。例如，如果元数据字段为 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 运算符。在同一组括号内组合运算符是无效的，例如：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，如果整个查询值仅包含一个 *（例如 "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"