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 {}
.