参考：排序和过滤

本文是对 Cloud Monitoring API 中 projects.alertPolicies、projects.notificationChannels 和 projects.uptimeCheckConfigs 的参考文档的补充。它提供了有关 API 使用 filter 和 orderBy 参数的语法详细信息。

以下 API 方法支持 filter 和 orderBy 参数：

• projects.alertPolicies.list
• projects.notificationChannels.list

以下 API 方法仅支持 filter 参数：

• projects.uptimeCheckConfig.list

排序和过滤基础知识

对 list 操作中的排序和过滤的支持由列表请求正文中存在 filter 和 orderBy 字符串字段表示（请参阅 API 参考文档，查看请求正文是否包含这些字段）。这两个字段都使用简单的语言引用要排序或过滤的对象中的字段。

排序顺序语法

orderBy 字段由一系列以逗号分隔的字段路径组成，这些路径可选添加前缀减号以逆转顺序。

例如，user_label.team,display_name 会按团队名称按升序排列，然后对同一团队的条目按显示名称按升序排列。如果您在其中一个字段前面添加一个减号，则该字段将按降序排列；例如，如果您想减少标题的详尽程度，则可以使用 -display_name.size 按标题长度排序，其中对象从最词首的标题到最短标题排列。

为了提供更实际的示例，user_label.team,display_name 首先按团队（按字典顺序）对结果进行分组，然后在每个团队分组中按标题（也按字典顺序排列）组织结果。

形式上，语法可以描述为：

   ORDER_BY_SPEC :=
      # Comma-separated list of fields.
      ORDERED_FIELD_LIST

   ORDERED_FIELD_LIST :=
      # Single field on which to sort.
      ORDERED_FIELD

      # Sort by the first field and then by the remaining fields.
      | ORDERED_FIELD "," ORDERED_FIELD_LIST

   ORDERED_FIELD :=
      # Sort by the field in ascending order.
      FIELD_REFERENCE

      # Sort by the field in descending order.
      | "-" FIELD_REFERENCE

   FIELD_REFERENCE :=
      # Simple field reference
      FIELD_NAME

      # Map value or list index lookup. For string-valued keys, the
      # supplied key in this notation must be quoted.
      | FIELD_NAME "[" LITERAL "]"

   FIELD_NAME :=
      # Immediate element
      IDENTIFIER

      # Subfield dereference or map element dereference. Note that,
      # in the case of maps, the IDENTIFIER on the left can also
      # be the singular form of the name of the map. That is, it is
      # permitted to use `user_label.mykey` and not just
      # `user_labels.mykey`. This is done for consistency with the
      # metric filters which permit `resource.label.` and `metric.label.`
      # which are in the singular form even though the map is `labels`.
      | IDENTIFIER "." FIELD_NAME

   LITERAL :=
       # Number
       [0-9]+(.[0.9]+)?

       # String literal using single quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  '[^']*'

       # String literal using double quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  "[^"]*"

       # Literal boolean true.
       |  true

       # Literal boolean false.
       |  false

   IDENTIFIER :=
       # Non-digit followed by any number of letters or digits.
       [a-zA-Z_]+[a-zA-Z0-9_]*

过滤器语法

过滤器语法由一种简单的表达式语言组成，用于从要过滤的对象的一个或多个字段构造谓词。使用 NOT、AND 和 OR 关键字编写否定、并列和排除。字段可使用 :（包含）、=（等式）、>（大于）、<（小于）、>=（大于或等于）、<=（小于或等于）和 !=（不等性）运算符与字面量值进行比较。内置函数 starts_with、ends_with、monitoring.regex.full_match（RE2 语法）以及内置属性 empty 和 size 为更高级的比较提供支持。

示例

要返回具有非空显示名或说明的所有条目，其中 user_labels 字段设置了 active 键（具有任意值），请执行以下操作：

(NOT display_name.empty OR NOT description.empty) AND user_labels='active'

要返回说明中包含“cloud”的所有条目，请执行以下操作：

description:'cloud'

要返回标题与“Temp XXXX”匹配的所有条目，请执行以下操作：

display_name=monitoring.regex.full_match('Temp \\d{4}')

正式规范

过滤器表达式语法可以汇总如下：

   FILTER_EXPRESSION :=
         # Negation
         "NOT" FILTER_EXPRESSION

         # Short-circuiting AND
         | FILTER_EXPRESSION "AND" FILTER_EXPRESSION

         # Short-circuiting OR
         | FILTER_EXPRESSION "OR" FILTER_EXPRESSION

         # Implicit short-circuiting AND
         | FILTER_EXPRESSION FILTER_EXPRESSION

         # Parenthesized sub-expression
         | "(" FILTER_EXPRESSION ")"

         # Basic expression
         | SIMPLE_EXPRESSION

   SIMPLE_EXPRESSION :=
         # Field implicitly converted to boolean
         FIELD_REFERENCE

         # Field binary comparison. Note that the right-hand side must
         # be compatible with the type on the left-hand side; one cannot
         # compare a number with a string. Sensible implicit conversions
         # are permitted, however; comparing an integer and double will
         # succeed with appropriate conversion/widening taking place.
         | FIELD_REFERENCE OP LITERAL

         # Function invocation
         | FIELD_REFERENCE "=" FUNCTION_EXPRESSION

   FIELD_REFERENCE :=
         # Simple field reference
         FIELD_NAME

         # Map value or list index lookup. For string-valued keys, the
         # supplied key in this notation must be quoted.
         | FIELD_NAME "[" LITERAL "]"

   FIELD_NAME :=
         # Immediate element
         IDENTIFIER

         # Subfield dereference or map element dereference. Note that,
         # in the case of maps, the IDENTIFIER on the left can also
         # be the singular form of the name of the map. That is, it is
         # permitted to use `user_label.mykey` and not just
         # `user_labels.mykey`. This is done for consistency with the
         # metric filters which permit `resource.label.` and `metric.label.`
         # which are in the singular form even though the map is `labels`.
         | IDENTIFIER "." FIELD_NAME

   OP :=
         # Equality comparison. Should be avoided for double-valued fields.
         "="

         # Less than.
         | "<"

         # Greater than.
         | ">"

         # Less than or equal.
         | "<="

         # Greater than or equal.
         | ">="

         # Containment. This is equivalent to '=' for numeric types.
         | ":"

         # Not equal.
         | "!="

   LITERAL :=
       # Number
       [0-9]+(.[0.9]+)?

       # String literal using single quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  '[^']*'

       # String literal using double quotes. Note that strings must
       # always be quoted. This is to avoid ambiguity with attempting
       # to refer to the value of a field.
       |  "[^"]*"

       # Literal boolean true.
       |  true

       # Literal boolean false.
       |  false

   FUNCTION_EXPRESSION :=
       # Starts with.
       "starts_with" "(" LITERAL ")"

       # Ends with.
       |  "ends_with" "(" LITERAL ")"

       # Has substring. Takes an optional second argument that indicates whether
       # the substring matching is case-sensitive (true) or not (false).
       # The default is false, providing case-insensitive matches.
       |  "has_substring" "(" LITERAL [, [true|false]] ")"

       # Regular expression match.
       |  "monitoring.regex.full_match" "(" LITERAL ")"

   IDENTIFIER :=
       # Non-digit followed by any number of letters or digits.
       [a-zA-Z_]+[a-zA-Z0-9_]*

支持的字段

可以在 filter 或 orderBy 字段中引用的字段取决于列出的对象的类型。

AlertPolicy

枚举 AlertPolicy 对象时，可以在 filter 和 orderBy 中引用以下字段：

• name
• display_name
• documentation.content
• documentation.mime_type
• user_labels
• conditions.size
• combiner
• enabled
• notification_channels

NotificationChannel

枚举 NotificationChannel 对象时，可以在 filter 和 orderBy 中引用以下字段：

• name
• type
• display_name
• description
• labels
• user_labels

UptimeCheckConfig

枚举 UptimeCheckConfig 对象时，可以在 filter 中引用以下字段：

• display_name
• user_labels
• selected_regions
• http_check.path
• http_check.headers
• http_check.port
• tcp_check.port
• monitored_resource.type
• monitored_resource.labels

高级主题

字段大小写

字段名称可以用 lower_case_with_underscores 和 camelCase 形式表示。也就是说，display_name 和 displayName 均受支持。

字符串

内置属性

字符串值字段会自动生成一个 size 属性，用于计算字符串中的 Unicode 字符数。例如，这将启用 display_name.size > 3 AND display_name.size < 10 等过滤器。除了 size 之外，字符串还有一个 empty 属性。

排序顺序

在 orderBy 中列出字符串时，系统会使用字符串的 UTF-8 表示法的字节顺序字典顺序来比较字符串；不会按照 Unicode 排序顺序对字符串进行排序。

隐式布尔值转换

如 user_label.enabled 中所示，可以在过滤器中将字符串隐式转换为布尔值。请注意，此转换与测试字符串非空不同；在此转换下，字符串的内容将被解析为布尔值，而将明确解析为布尔值的字符串将采用布尔值；如果字符串明显不是布尔值，则将非空字符串解释为 true，并将空字符串解释为 false。

与“false”、“f”、“no”、“n”或“0”匹配（不区分大小写）的字符串会被视为完全 false；与“true”、“t”、“yes”、“y”或“1”字符串（不区分大小写）的字符串会被视为完全 true。

列表

内置属性

列表值字段会自动生成一个 size 属性，用于计算该列表中的元素数量。例如，您可以在 orderBy 中使用 notification_channels.size，按提醒所通知的渠道数量对提醒政策进行排序。

用于二进制比较

在使用一系列二进制运算符之一将列表值字段与字面量进行比较时，系统会将比较结果视为应用元素级比较，然后计算结果的 OR。例如，如果任何通知渠道的子字符串为“123”，则过滤器 notification_channels:"123" 的计算结果将为 true。对于 != 运算符，具体而言，元素级比较是 AND 运算，而非 OR 运算；换句话说，对于 !=，不允许任何元素匹配。或者，要重新声明，x!=y 在逻辑上等同于伪代码 x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y，而 x=y 在逻辑上等同于伪代码 x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y。此不一致旨在解决 x!=y 的可能意图，并避免与返回结果包含禁止/过滤值的此类表达式相混淆。

除了限制整个列表之外，还可以通过索引 ([]) 运算符引用特定列表条目。例如，您可以使用 notification_channels[0]:"123" 仅测试第一个元素。如果存在超出范围的索引，则会生成默认值（空、零等）。

隐式转换为布尔值

在没有二进制比较的过滤器中指定时，列表会隐式转换为布尔值。此转换不同于测试列表是否非空；a_list 和 NOT a_list.empty 会针对 {false, false, false} 或其他任何非空列表返回不同的结果，这些列表的值都会隐式转换为布尔值 false。

地图

内置属性

映射值字段会自动生成一个 size 属性，用于计算该映射中的元素数量。例如，您可以在 orderBy 中使用 user_labels.size，按定义的用户标签数进行排序。同样，布尔值的 empty 属性也是自动生成的。

注意：如果您的映射包含名为 size 的键，则使用 user_labels.size 来引用映射中的元素数量，并使用 user_labels['size'] 引用用户标签键 size 的值。empty 属性也是如此。

测试键是否存在

您可以使用各种受支持的二进制运算符将映射与字面量值进行比较。该解释在逻辑上等同于通过提取映射的键并执行比较来将映射投影到列表中。要提供示例，您可以使用 user_labels="phase" 来确定 user_labels映射是否包含其值等于“phase”的键。

使用键引用值

可以使用两种表示法之一引用映射条目：点 (.）) 表示法和索引 ([]) 表示法。例如，您可以使用 user_labels.team 或 user_labels['team'] 来引用 user_labels 字段中与键“team”对应的值。为了与使用 metric.label. 和 resource.label. 前缀（而不是 metric.labels. 和 resource.labels.）的指标 API 保持一致，映射字段也可以使用单数形式的名称来引用（例如，允许使用 user_label.team）。请注意，对于名为 size 或 empty 的键，您必须使用索引表示法；使用点表示法会引用内置映射属性。

隐式转换为布尔值

在隐式转换为布尔值中，如果映射为非空并且至少有一个映射 *值，则相应映射会被视为 true（隐式转换为 true）。这与测试映射是否非空不同。

按复合类型排序

可以在过滤条件中引用的所有字段也可以在 order_by 中引用。这也适用于复杂类型和复合类型。这些类型的排序顺序稳定且定义明确，但不一定直观；因此，我们不建议使用这种用法。

列表

列表是使用元素级的字典顺序比较进行比较的，其中较小的列表在其共同元素相同的情况下排在最前面。举例来说，{0, 1} 小于 {0, 2} 但大于 {0}。

地图

通过对与键的并集对应的映射值进行元素级比较来比较映射。对于在一个映射中定义但未在另一个映射中定义的键，将使用默认值（空、零等）进行比较。 举例来说，{"x":0, "y":0} 小于 {"x":1, "y":1} 但大于 {"a":-1} 且等于 {}。