参考：排序和过滤

本文档介绍了如何对适用的 Cloud Monitoring API 命令的结果进行排序和过滤。借助排序功能，您可以指定结果列表中元素的顺序。过滤功能可让您定义结果列表中应包含哪些元素的属性。您可以使用 orderBy 和 filter 字段对 API 响应进行排序和过滤。

下表列出了支持排序或过滤的 Cloud Monitoring API 方法：

方法	支持排序	支持过滤
`projects.alertPolicies.list`	是	是
`projects.notificationChannels.list`	是	是
`projects.snoozes.list`	否	是
`projects.uptimeCheckConfig.list`	否	是

排序和过滤基础知识

如果列表请求正文中存在 orderBy 和 filter 字符串字段，则表示支持 list 操作中的排序和过滤。请参阅 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 :=
       # Whole or real 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 XYZ”匹配的所有条目，请执行以下操作：

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

正式规范

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

   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 :=
       # Whole or real 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

       # Date and Time formatted as per RFC-3339 standards using
       # double quotes.
       |  "YYYY-MM-DDT00:00:00-00:00"

   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
已启用
notification_channels

`NotificationChannel`

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

name
type
display_name
说明
标签
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

`Snoozes`

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

interval.start_time
interval.end_time

高级主题

本部分详细介绍了如何对 API 结果进行排序和过滤。

字段大小写

字段名称可采用 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 属性也是自动生成的。

测试键是否存在

可使用各种受支持的二进制运算符将映射与字面量值进行比较。该解释在逻辑上等同于通过提取映射的键并执行比较来将映射投影到列表中。例如，您可以使用 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} 且等于 {}。

参考：排序和过滤 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

排序和过滤基础知识

排序顺序语法

过滤器语法

示例

正式规范

支持的字段

AlertPolicy

NotificationChannel

UptimeCheckConfig

Snoozes

高级主题

字段大小写

字符串

列表

地图

按复合类型排序

参考：排序和过滤

`AlertPolicy`

`NotificationChannel`

`UptimeCheckConfig`

`Snoozes`