查询语法

如需搜索资源，您可以通过指定 FIELD、运算符和 QUERY 来过滤搜索结果。

文本完全匹配：等于 (=) 运算符

FIELD=QUERY

查询示例：owner=[e-mail]。

equals (=) 运算符会检查 QUERY 是否与资源元数据 FIELD 的值完全匹配。区分大小写。对于重复字段，如果 QUERY 与某个字段的某个值匹配，则资源将被视为匹配。支持的 FIELD 名称取决于查询是资源搜索还是 Identity and Access Management (IAM) 政策搜索。QUERY 是一个短语，但不能包含通配符。

文本部分匹配：包含 (:) 运算符

FIELD:QUERY

查询示例：owner: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] 联系我们。

示例

例如，owner 字段值为 "[e-mail]" 的资源与以下查询匹配：

• 匹配的原因是词组与字段值完全一样。

    owner=[e-mail]
  

• 匹配的原因是标点符号被视为分隔符，并且不区分大小写。

    owner:[e-mail]
  

• 匹配的原因是短语中的字词按顺序匹配。请注意，"amy 2020 gmail" 是一个短语；字词会按顺序且连续匹配。

    owner:"amy 2020 gmail"
  

• 匹配的原因是字词组合可以按任意顺序显示。请注意，(gmail 2020 amy) 是一个组合；字词会进行匹配并且不一定按顺序。

    owner:(gmail 2020 amy)
  

• 匹配的原因是短语中的字词按顺序匹配，而组合中的字词以任意顺序显示。请注意，"amy 2020" 是一个短语，字词会按顺序且连续匹配。(gmail "amy 2020") 是一个组合；gmail 和 "amy 2020" 不一定按顺序进行匹配。

    owner:(gmail "amy 2020")
  

• 匹配的原因是可以在短语中使用 * 来表示前缀匹配。

    owner:amy-20*
  

其 owner 字段的值为 "[e-mail]" 的资产与以下查询不匹配：

• 不匹配的原因是词组区分大小写。请改用 has (:) 运算符进行不区分大小写匹配。

    owner=[e-mail]
  

• 不匹配，因为词组部分与字段的值匹配。请改用 has (:) 运算符进行部分匹配。

    owner=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"
  

Phrase

短语是用双引号 (") 引起来的一个或多个字词。对于短语，字词的顺序很重要。短语中的字词必须按顺序并且连续匹配。请注意，如果要不考虑顺序地匹配多个字词，您必须使用组合（例如，field:(word1 word2 word3)）。

注意：如果短语仅包含英文字符 [a-zA-Z]、数字 [0-9]、基本电子邮件/网址连接符 [_-+.@/&] 和通配符 [*]，则无需将其用双引号引起。如果被括起的短语中包含 " 或 \，则需要将其转义为\" 或 \\。您也可以将 " 或 \ 替换为单个空格，因为在执行搜索时，非字母数字字符被视为分隔符。

以下表达式是相同的：

owner:amy
owner:"amy"

owner:[e-mail]
owner:"[e-mail]"

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

以下短语必须用引号括起：

name:"my instance"

owner:"[e-mail]"

description:"domain:gmail.com"

description:"hello \"world\""

description:"hello\\world"

示例：短语

• 返回 owner 字段按顺序且连续包含字词 amy 和字词 2020 的资源：

  owner:"amy 2020"
  

• 如果您的资源的 owner 字段值为 "[e-mail]"，则上述查询匹配。

• 如果您的资源的 owner 字段值为 "[e-mail]"，则上述查询不会匹配，因为字词顺序不匹配。

• 如果您的资源的 owner 字段值为 "[e-mail]"，则上述查询不匹配，因为字词并不连续匹配。

组合

搜索短语可以使用 AND 或 OR 进行组合。您需要使用括号将组合括起来。

注意：运算符 AND 和 OR 必须大写。在查询中同时使用 AND 和 OR 时，必须恰当地使括号来对组合进行分组。

示例：组合

• 返回 owner 字段同时包含字词 amy 和字词 john（但无需考虑顺序）的资产。AND 在组合中是可选的。请注意，如需按顺序匹配多个字词，您必须使用短语（例如field:"word1 word2 word3")。

  owner:(amy john)
  

  注意：如果资产包含一个具有一系列值的字段，例如 owner=["[e-mail]", "[e-mail]", "[e-mail]"]。使用 owner:(amy john) 进行搜索时会与该资产匹配，因为 [e-mail] 包含字词 amy，并且 [e-mail] 包含字词 john。它不保证此字段只有同时包含字词 amy 和字词 john 的单个元素（如 [e-mail]）。

• 返回 owner 字段具有字词 amy 或字词 john 的资源。

  owner:(amy OR john)
  

• 返回 owner 字段同时包含字词 amy 和字词 john 或包含字词 bob 的资源。

  owner:((amy john) OR bob)
  

  注意：您必须恰当地使用括号以对组合进行分组。对于上述查询，您不能省略括号。以下查询为非法查询：owner:(amy john OR bob)。

• 返回 owner 字段同时包含字词 amy 和字词 john 或 name 字段包含字词 bob 的资源。

  owner:(amy john) OR name:bob
  

排除搜索过滤条件

可以使用 NOT 运算符排除搜索过滤器。支持圆括号，但不作强制要求。

注意：NOT 运算符必须大写。只有在搜索资源时才支持排除操作。

示例：排除搜索过滤条件

• 返回 state 字段不包含 ACTIVE 一词的资产。

  NOT state:ACTIVE
  

• 返回 owner 字段既不包含 amy 一词又不包含 john 一词的资产。

  NOT owner:(amy OR john)
  

• 返回 networkTags 字段不包含 internal 一词或 private 一词的资产。

  NOT (networkTags:internal OR networkTags:private)
  

通配符

星号 (*) 可以在短语中用作通配符。根据其位置，可能具有不同的含义。

• 如果它位于短语的末尾，例如："am 20*" 是一个令牌前缀匹配索引。该查询等于 (am* 20*)。它与包含以“am”开头的令牌的字段相匹配，例如：“amy”以及以“20”开头的令牌，例如："2021"。前缀的顺序无关紧要。

• 如果整个词组仅包含一个 *，例如："labels.env:*"，则由其执行检查。检查指定标签键“env”是否存在。不支持其他字段。

• 如果它位于短语中间，例如："compute*storage" 被视为令牌化分隔符。该查询等效于“计算存储”。

• 如果既有短语又有短语的末尾，例如"*compute storage*" 被视为令牌化分隔符。该查询等效于“计算存储”。

示例：令牌前缀匹配

• 返回 owner 字段包含以 am 开头的字词的资源：

  owner:am*
  

• 返回 owner 字段包含两个字词且 "amy" 和 "20" 作为前缀的资源：

  owner:"amy 20*"
  
  owner:"20 amy*"
  

• 如果您的 owner 字段值为 "[e-mail]"，则上述查询均匹配。令牌化后，"amy" 和 "20" 都是前缀。请注意，查询字符串 "amy 20*" 与 "amy 20" 不同。后者要求 20 是一个完整的字词，而不是前缀。

示例：标签键存在性

• 返回 labels 具有“env”键且具有任何值（包括空值或没有值）的资产：

  labels.env:*