Referencia: Ordenamiento y filtrado

Este documento complementa la documentación de referencia para projects.alertPolicies, projects.notificationChannels y projects.uptimeCheckConfigs en la API de Cloud Monitoring. Proporciona detalles sintácticos sobre los parámetros filter y orderBy cuando la API los usa.

Los siguientes métodos de API admiten los parámetros filter y orderBy:

El siguiente método de API solo admite el parámetro filter:

Conceptos básicos sobre el ordenamiento y filtrado

La asistencia para ordenar y filtrar en una operación de list se indica por la presencia de campos de string filter y orderBy en el cuerpo de la solicitud de lista (consulta la documentación de referencia de la API para ver si el cuerpo de la solicitud tiene estos campos). Ambos campos usan un lenguaje simple para referirse a los campos en el objeto que se ordena o filtra.

Sintaxis de orden de clasificación

El campo orderBy consta de una lista separada por comas de las rutas de los campos, a las que se les puede prefijar un signo menos para revertir el orden.

Por ejemplo, los ordenamientos de user_label.team,display_name por nombre de equipo en orden ascendente y, luego, para entradas con el mismo equipo, ordenamientos por nombre visible, también en orden ascendente. Si agregas un signo menos delante de uno de los campos separados por comas, ese campo se ordena en orden descendente. Por ejemplo, si intentas reducir la verbosidad de tus títulos, puedes usar -display_name.size para ordenarlos por la longitud del título, con los objetos ordenados del título más extenso al más corto.

Para proporcionar un ejemplo más realista, user_label.team,display_name agrupa los resultados primero por equipo (en orden lexicográfico) y, luego, dentro de cada agrupación, organiza los resultados 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 :=
       # 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 expresión simple para la construcción de un predicado de uno o más campos del objeto que se filtra. La negación, la conjunción y la disyunción se escriben mediante las palabras clave NOT, AND y OR. Los campos se pueden comparar con valores literales mediante el uso de los operadores : (contención), = (igualdad), > (mayor que), < (menor que), >= (mayor que o igual a), <= (menor que o igual a) y != (desigualdad). Las funciones integradasstarts_with, ends_with, monitoring.regex.full_match (sintaxis RE2) y las propiedades integradas empty y size proporcionan asistencia para comparaciones más avanzadas.

Ejemplos

Mostrar todas las entradas con un nombre visible o una descripción que no estén vacíos, en los que el campo user_labels tiene la clave active configurada (con cualquier valor):

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

Mostrar todas las entradas cuya descripción contiene "cloud":

description:'cloud'

Mostrar todas las entradas cuyo título coincida con "Temp XXXX":

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

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 :=
       # 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_]*

Campos disponibles

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

AlertPolicy

Se puede hacer referencia a los siguientes campos en filter y orderBy cuando se enumeran objetos AlertPolicy:

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

NotificationChannel

Se puede hacer referencia a los siguientes campos en filter y orderBy cuando se enumeran objetos NotificationChannel:

  • name
  • tipo
  • display_name
  • description
  • labels
  • user_labels

UptimeCheckConfig

Se puede hacer referencia a los siguientes campos en filter cuando se enumeran 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

Temas avanzados

Mayúsculas y minúsculas en los campos

Los nombres de campo se pueden expresar en los formatos lower_case_with_underscores y camelCase. Es decir, display_name y displayName son compatibles.

Strings

Propiedades integradas

Los campos con valores de string tienen una propiedad size generada automáticamente que calcula la cantidad de caracteres Unicode en la string. Esto habilita, por ejemplo, un filtro como display_name.size > 3 AND display_name.size < 10. Además de size, las strings también tienen una propiedad booleana empty.

Orden

Cuando se muestra una string en orderBy, las strings se comparan mediante el orden lexicográfico por bytes en la representación UTF-8 de la string. Las strings no se ordenan según el orden de intercalación de Unicode.

Conversión booleana implícita

Es posible convertir una string de forma implícita en booleana en un filtro como en user_label.enabled. Ten en cuenta que esta conversión no es idéntica a la prueba de que la string no está vacía. En esta conversión, el contenido de la string se analiza en un valor booleano. Las strings que se analicen de forma clara en un valor booleano, toman ese valor. Si la string no tiene un valor booleano obvio, las strings que no están vacías se interpretarán como verdaderas y las vacías como falsas.

Las strings que coinciden en mayúsculas y minúsculas con "false", "f", "no", "n" o "0" se consideran falsas sin ninguna ambigüedad. Las strings que coinciden en mayúsculas y minúsculas con "true", "t", "yes", "y" o "1" se consideran verdaderas sin ninguna ambigüedad.

Listas

Propiedades integradas

Los campos con valores de lista tiene una propiedad size generada automáticamente que calcula la cantidad de elementos en esa lista. Por ejemplo, puedes usar notification_channels.size en orderBy para ordenar las políticas de alertas en función de la cantidad de canales que notifican.

Uso en comparaciones binarias

Cuando se compara un campo con valores de lista con un literal mediante uno de los diversos operadores binarios, la comparación se interpreta como si aplicara una comparación en términos de elementos y, luego, calculara el 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 substring. En el operador !=, en particular, se usa AND, en lugar de OR, para la comparación en términos de elementos. En otras palabras, en !=, no se permite que ninguno de los elementos coincida. O bien, para rectificar, x!=y es el equivalente lógico del seudocódigo x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, mientras que x=y es el equivalente lógico del seudocódigo x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Esta inconsistencia está diseñada para abordar el intent probable de x!=y y evitar confusiones con una expresión que muestre resultados que contengan el valor prohibido o filtrado.

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

Conversión implícita a un valor booleano

Una lista se convertirá de manera implícita en un valor booleano cuando se especifique en un filtro sin una comparación binaria. Esta conversión es diferente de la prueba de que la lista no está vacía. a_list y NOT a_list.empty muestran resultados diferentes para {false, false, false} o cualquier otra lista que no esté vacía y cuyos valores sean o se conviertan de forma implícita en el valor booleano false.

Maps

Propiedades integradas

Los campos con valores de mapa tiene una propiedad size generada automáticamente que calcula la cantidad de elementos en ese mapa. Por ejemplo, puedes usar user_labels.size en orderBy para ordenar en función de la cantidad de etiquetas de usuario definidas. De manera similar, una propiedad empty con un valor booleano también se genera automáticamente.

Prueba la existencia de clave

Los mapas se pueden comparar con valores literales con los diversos operadores binarios admitidos. La interpretación es el equivalente lógico de la proyección del mapa en una lista mediante la extracción de las claves del mapa y la ejecución de la comparación. Para dar un ejemplo, puedes usar user_labels="phase" a fin de determinar si el mapa user_labels contiene una clave cuyo valor sea igual a “fase”.

Haz referencia a valores por clave

Se puede hacer referencia a las entradas del mapa mediante una de estas dos notación: notación de punto (.) y de índice ([]). Por ejemplo, puedes usar user_labels.team o user_labels['team'] para hacer referencia al valor que corresponde al “equipo” de la clave en el campo user_labels. Para mantener la coherencia con la API de métricas 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, para las claves llamadas size o empty, debes usar la notación de índice. El uso de la notación de puntos hará referencia a las propiedades integradas del mapa.

Conversión implícita a un valor booleano

En las conversiones implícitas a bool, se considera que un mapa es verdadero si no está vacío y tiene al menos un *value de mapa (se convierte implícitamente en verdadero). Esto no es lo mismo que probar que el mapa no esté vacío.

Ordena por tipos compuestos

También se puede hacer referencia a todos los campos a los que se puede hacer referencia en un filtro 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 es necesariamente intuitivo. Por lo tanto, se desaconseja este uso, aunque está permitido.

Listas

Las listas se comparan mediante una comparación lexicográfica en términos de elementos, con la lista más pequeña en primer lugar en el caso de que sus elementos comunes sean iguales. Para dar un ejemplo, {0, 1} es menor que {0, 2}, pero mayor que {0}.

Maps

Los mapas se comparan mediante una comparación en términos de elementos de los valores del mapa que se corresponden a la unión de sus claves. En el caso de las claves que están definidas en un mapa, pero no el otro, se usa un valor predeterminado (vacío, cero, etc.) para la comparación. Para dar un ejemplo, {"x":0, "y":0} es menor que {"x":1, "y":1}, pero mayor que {"a":-1} e igual a {}.