Referencia: ordenar y filtrar

En este documento se describe cómo puede ordenar y filtrar los resultados de los comandos de la API de Cloud Monitoring aplicables. La ordenación te permite especificar el orden de los elementos de la lista de resultados. Los filtros le permiten definir las propiedades de los elementos que se incluyen en la lista de resultados. Puedes usar los campos orderBy y filter para ordenar y filtrar la respuesta de la API.

En la siguiente tabla se indican los métodos de la API Cloud Monitoring que admiten ordenación o filtrado:

Método	Admite la ordenación	Admite el filtrado
projects.alertPolicies.list	Sí	Sí
projects.notificationChannels.list	Sí	Sí
projects.snoozes.list	No	Sí
projects.uptimeCheckConfig.list	No	Sí

Aspectos básicos de la ordenación y el filtrado

La presencia de los campos de cadena orderBy y filter en el cuerpo de la solicitud de lista indica que se admite la ordenación y el filtrado en una operación list. Consulta la documentación de referencia de la API para determinar si el cuerpo de la solicitud incluye estos campos.

Sintaxis de ordenación

El campo orderBy consta de una lista de rutas de campos separadas por comas que, opcionalmente, pueden llevar un signo menos delante para invertir el orden.

Por ejemplo, user_label.team,display_name pedidos por nombre de equipo en orden ascendente y, a continuación, en las entradas con el mismo equipo, pedidos por nombre visible, también en orden ascendente. Si añade un signo menos delante de uno de los campos separados por comas, ese campo se ordenará de forma descendente. Por ejemplo, si quiere reducir la longitud de los títulos, puede usar -display_name.size para ordenar por longitud, de forma que los objetos se ordenen del título más largo al más corto.

Para ofrecer un ejemplo más realista, user_label.team,display_name agrupa los resultados primero por equipo (en orden lexicográfico) y, a continuación, dentro de cada grupo, los organiza por título (también en orden lexicográfico).

Formalmente, la sintaxis se puede describir de la siguiente manera:

   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_]*

Sintaxis de filtro

La sintaxis del filtro consta de un lenguaje de expresiones para crear un predicado a partir de uno o varios campos de los objetos que se están filtrando. La negación, la conjunción y la disyunción se escriben con las palabras clave NOT, AND y OR. Los campos se pueden comparar con valores literales mediante los operadores : (contención), = (igualdad), > (mayor que), < (menor que), >= (mayor o igual que), <= (menor o igual que) y != (desigualdad). Las funciones integradas starts_with, ends_with y monitoring.regex.full_match (sintaxis RE2) y las propiedades integradas empty y size permiten hacer comparaciones más avanzadas.

Ejemplos

Para devolver todas las entradas con un nombre visible o una descripción no vacíos en los que el campo user_labels tenga la clave active definida (con cualquier valor), haz lo siguiente:

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

Para devolver todas las entradas cuya descripción contenga "cloud", haz lo siguiente:

description:'cloud'

Para devolver todas las entradas cuyo título coincida con "Temp XYZ":

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

Especificación formal

La sintaxis de la expresión de filtro se puede resumir de la siguiente manera:

   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_]*

Campos admitidos

Los campos a los que se puede hacer referencia en los campos filter o orderBy dependen del tipo de objeto que se esté mostrando.

AlertPolicy

Los siguientes campos se pueden consultar en filter y orderBy al enumerar objetos AlertPolicy:

• name
• display_name
• documentation.content
• documentation.mime_type
• user_labels
• conditions.size
• combinador
• habilitada
• notification_channels

NotificationChannel

Los siguientes campos se pueden consultar en filter y orderBy al enumerar objetos NotificationChannel:

• name
• tipo
• display_name
• description
• etiquetas
• user_labels

UptimeCheckConfig

Los siguientes campos se pueden consultar en filter al enumerar objetos UptimeCheckConfig:

• 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

Los siguientes campos se pueden consultar en filter al enumerar objetos Snoozes:

• interval.start_time
• interval.end_time

Temas avanzados

En esta sección se ofrece más información sobre cómo ordenar y filtrar los resultados de la API.

Revestimiento de campo

Los nombres de campo se pueden expresar tanto en formato lower_case_with_underscores como camelCase. Es decir, se admiten tanto display_name como displayName.

Cadenas

Propiedades integradas

Los campos con valores de cadena tienen automáticamente una propiedad size generada que calcula el número de caracteres Unicode de la cadena. De esta forma, se puede aplicar un filtro como display_name.size > 3 AND display_name.size < 10. Además de size, las cadenas también tienen una propiedad booleana empty.

Orden

Cuando se incluye una cadena en orderBy, las cadenas se comparan mediante el orden lexicográfico por bytes en la representación UTF-8 de la cadena. Las cadenas no se ordenan según el orden de clasificación Unicode.

Conversión implícita a bool

Es posible convertir implícitamente una cadena en un valor booleano en un filtro, como en user_label.enabled. Ten en cuenta que esta conversión no es idéntica a comprobar que la cadena no está vacía. En esta conversión, el contenido de la cadena se analiza para obtener un valor booleano. Las cadenas que se analizan de forma inequívoca para obtener un valor booleano adoptan ese valor. Si la cadena no tiene un valor booleano obvio, las cadenas no vacías se interpretan como verdaderas y las cadenas vacías se interpretan como falsas.

Las cadenas que coinciden sin distinguir entre mayúsculas y minúsculas con "false", "f", "no", "n" o "0" se consideran inequívocamente falsas. Las cadenas que coinciden sin distinguir entre mayúsculas y minúsculas con "true", "t", "yes", "y" o "1" se consideran inequívocamente verdaderas.

Listas

Propiedades integradas

Los campos con valores de lista tienen automáticamente una propiedad size generada que calcula el número de elementos de esa lista. Por ejemplo, puedes usar notification_channels.size en orderBy para ordenar las políticas de alertas por el número de canales a los que envían notificaciones.

Usar en comparaciones binarias

Cuando se compara un campo con valores de lista con un literal mediante uno de los distintos operadores binarios, la comparación se interpreta como una comparación elemento a elemento y, a continuación, se calcula el operador OR de los resultados. Por ejemplo, el filtro notification_channels:"123" se evaluará como verdadero si alguno de los canales de notificación tiene "123" como subcadena. En el caso del operador !=, la comparación por elementos se realiza con el operador AND en lugar de con el operador OR. En otras palabras, en el caso de !=, no se permite que coincida ninguno de los elementos. O, dicho de otro modo, x!=y es lógicamente equivalente al pseudocódigo x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, mientras que x=y es lógicamente equivalente al pseudocódigo x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Esta incoherencia se ha diseñado para abordar la intención probable de x!=y y evitar confusiones con una expresión que devuelva resultados que contengan el valor filtrado.

Además de restringir la lista en su conjunto, también es posible hacer referencia a entradas específicas de la lista mediante el operador de indexación ([]). Por ejemplo, puedes usar notification_channels[0]:"123" para probar solo el primer elemento. Se genera un valor predeterminado (vacío, cero, etc.) en el caso de los índices fuera de los límites.

Conversión implícita a bool

Si se especifica en un filtro sin una comparación binaria, una lista se convertirá implícitamente en booleana. Esta conversión es distinta de la prueba de que la lista no está vacía. a_list y NOT a_list.empty devuelven resultados diferentes para {false, false, false} o cualquier otra lista no vacía cuyos valores sean o se conviertan implícitamente en el valor booleano false.

Maps

Propiedades integradas

Los campos con valores de mapa tienen automáticamente una propiedad size generada que calcula el número de elementos de ese mapa. Por ejemplo, puedes usar user_labels.size en orderBy para ordenar por el número de etiquetas de usuario definidas. Del mismo modo, también se genera automáticamente una propiedad empty con valor booleano.

Nota: Si tu mapa contiene una clave llamada size, usa user_labels.size para hacer referencia al número de elementos del mapa y user_labels['size'] para hacer referencia al valor de la clave de etiqueta de usuario size. Lo mismo ocurre con la propiedad empty.

Comprobar si existe la clave

Los mapas se pueden comparar con valores literales mediante los distintos operadores binarios admitidos. La interpretación es lógicamente equivalente a proyectar el mapa en una lista extrayendo las claves del mapa y, a continuación, ejecutando la comparación. Por ejemplo, puede usar user_labels="phase" para determinar si el mapa user_labels contiene una clave cuyo valor sea igual a "phase".

Hacer referencia a valores por clave

Se puede hacer referencia a las entradas de un mapa mediante dos notaciones: la notación de punto (.) y la notación de índice ([]). Por ejemplo, puedes usar user_labels.team o user_labels['team'] para hacer referencia al valor correspondiente a la clave "team" en el campo user_labels. Para mantener la coherencia con la API Metrics, que usa los prefijos metric.label. y resource.label. en lugar de metric.labels. y resource.labels., también se puede hacer referencia a los campos de mapa con la forma singular del nombre (por ejemplo, también se permite user_label.team). Ten en cuenta que, en el caso de las claves llamadas size o empty, debes usar la notación de índice, ya que la notación de puntos hará referencia a las propiedades de mapa integradas.

Conversión implícita a bool

En las conversiones implícitas a bool, un mapa se considera verdadero si no está vacío y al menos un valor del mapa se convierte implícitamente en verdadero. No es lo mismo que comprobar que el mapa no está vacío.

Ordenar por tipos compuestos

Todos los campos a los que se puede hacer referencia en un filtro también se pueden usar en order_by. Esto también se aplica a los tipos complejos y compuestos. El orden de clasificación de estos tipos es estable y está bien definido, aunque no sea necesariamente intuitivo. Por lo tanto, se permite este uso, pero no se recomienda.

Listas

Las listas se comparan mediante una comparación lexicográfica elemento a elemento, y la lista más corta se coloca en primer lugar si los elementos comunes son iguales. Por ejemplo, {0, 1} es menor que {0, 2}, pero mayor que {0}.

Maps

Los mapas se comparan realizando una comparación elemento a elemento de los valores del mapa correspondientes a la unión de sus claves. En el caso de las claves definidas en un mapa, pero no en el otro, se utiliza un valor predeterminado (vacío, cero, etc.) para la comparación. Por ejemplo, {"x":0, "y":0} es menor que {"x":1, "y":1}, pero mayor que {"a":-1} e igual que {}.