Référence : tri et filtrage

Ce document complète la documentation de référence sur projects.alertPolicies, projects.notificationChannels et projects.uptimeCheckConfigs dans l'API Cloud Monitoring. Elle fournit des détails syntaxiques sur les paramètres filter et orderBy lorsqu'ils sont utilisés par l'API.

Les méthodes d'API suivantes sont compatibles avec les paramètres filter et orderBy:

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

La méthode API suivante n'accepte que le paramètre filter:

• projects.uptimeCheckConfig.list

Principes de base du tri et du filtrage

La possibilité de trier et de filtrer les résultats d'une opération list est indiquée par la présence des champs de chaîne filter et orderBy dans le corps de la requête de liste (consultez la documentation de référence de l'API pour voir si le corps de la requête inclut ces champs). Ces deux champs font appel à une syntaxe simple pour faire référence aux champs de l'objet trié ou filtré.

Syntaxe de l'ordre de tri

Le champ orderBy est constitué d'une liste de chemins d'accès à des champs séparés par des virgules et éventuellement précédés d'un signe "moins" pour inverser l'ordre.

Par exemple, user_label.team,display_name effectue un tri par nom d'équipe dans l'ordre croissant, puis, pour les entrées de la même équipe, effectue un tri par nom d'affichage, également dans l'ordre croissant. Si vous ajoutez un signe moins devant l'un des champs séparés par une virgule, ce champ est trié par ordre décroissant. Par exemple, si vous essayez de réduire le niveau de détail de vos titres, vous pouvez utiliser -display_name.size pour effectuer un tri par longueur de titre, avec des objets classés du titre le plus long au titre le plus court.

Pour fournir un exemple plus réaliste, user_label.team,display_name regroupe d'abord les résultats par équipe (dans l'ordre lexicographique), puis, dans chaque groupe d'équipe, organise les résultats par titre (également dans l'ordre lexicographique).

Formellement, la syntaxe peut être décrite comme suit :

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

Syntaxe des filtres

La syntaxe des filtres consiste en un langage d'expression simple permettant de construire un prédicat à partir d'un ou de plusieurs champs des objets filtrés. La négation, la conjonction et la disjonction sont écrites à l'aide des mots clés NOT, AND et OR. Les champs peuvent être comparés à des valeurs littérales à l'aide des opérateurs : (contient), = (égal à), > (supérieur à), < (inférieur à), >= (supérieur ou égal à), <= (inférieur ou égal à) et != (différent de). Les fonctions intégrées starts_with, ends_with, monitoring.regex.full_match (syntaxe RE2), ainsi que les propriétés intégrées empty et size permettent d'effectuer des comparaisons plus poussées.

Exemples

Pour renvoyer toutes les entrées avec un nom à afficher ou une description non vide dans lequel la clé active du champ user_labels est définie (avec n'importe quelle valeur) :

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

Pour renvoyer toutes les entrées dont la description contient "cloud" :

description:'cloud'

Pour renvoyer toutes les entrées dont le titre correspond à "Temp XXXX" :

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

Spécification formelle

La syntaxe de l'expression de filtre peut être résumée comme suit :

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

Champs pris en charge

Les champs pouvant être référencés dans les champs filter ou orderBy dépendent du type d'objet répertorié.

AlertPolicy

Les champs suivants peuvent être référencés dans filter et orderBy lors de l'énumération des objets AlertPolicy:

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

NotificationChannel

Les champs suivants peuvent être référencés dans filter et orderBy lors de l'énumération des objets NotificationChannel:

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

UptimeCheckConfig

Les champs suivants peuvent être référencés dans filter lors de l'énumération des objets 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

Rubriques avancées

Casse des champs

Les noms de champs peuvent être exprimés au format lower_case_with_underscores et camelCase. Cela signifie que display_name et displayName sont tous deux acceptés.

Chaînes

Propriétés intégrées

Les champs à valeur de chaîne comportent automatiquement une propriété size générée qui calcule le nombre de caractères Unicode dans la chaîne. Cela permet, par exemple, d'appliquer un filtre tel que display_name.size > 3 AND display_name.size < 10. En plus de size, les chaînes disposent également d'une propriété empty booléenne.

Ordre de tri

Lorsque vous répertoriez une chaîne dans orderBy, les chaînes sont comparées à l'aide d'un ordre lexicographique par octets dans la représentation UTF-8 de la chaîne. Les chaînes ne sont pas triées en fonction de l'ordre de classement Unicode.

Conversion implicite en booléen

Il est possible de convertir implicitement une chaîne en booléen dans un filtre, comme dans user_label.enabled. Notez que cette conversion n'est pas identique au test visant à vérifier que la chaîne n'est pas vide. Lors de cette conversion, le contenu de la chaîne est analysé en booléen, et les chaînes qui sont analysées sans ambiguïté en booléen prennent cette valeur booléenne. Si la chaîne n'est pas manifestement une valeur booléenne, les chaînes non vides sont interprétées comme étant "true" et les chaînes vides comme étant "false".

Les chaînes qui ne correspondent pas aux valeurs non sensibles à la casse "false", "f", "no", "n" ou "0" sont considérées comme certainement fausses. Les chaînes qui ne correspondent pas aux valeurs non sensibles à la casse "true", "t", "yes", "y" ou "1" sont considérées comme certainements vraies.

Listes

Propriétés intégrées

Les champs de type liste comportent automatiquement une propriété size générée qui calcule le nombre d'éléments figurant dans cette liste. Par exemple, vous pouvez utiliser notification_channels.size dans orderBy pour trier les règles d'alerte en fonction du nombre de canaux qu'ils envoient.

Utilisation dans des comparaisons binaires

Lors de la comparaison d'un champ de type liste à un littéral avec l'un des différents opérateurs binaires, la comparaison est interprétée comme appliquant une comparaison par élément, puis calculant l'opération OR des résultats. Par exemple, le filtre notification_channels:"123" renvoie la valeur "true" si l'un des canaux de notification a "123" comme sous-chaîne. Pour l'opérateur !=, plus précisément, la comparaison par élément est combinée à l'opérateur AND plutôt qu'à l'opérateur OR. Autrement dit, pour !=, aucun des éléments n'est autorisé à correspondre. Ou, pour reformuler, x!=y équivaut logiquement au pseudo-code x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, tandis que x=y équivaut logiquement au pseudo-code x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Cette incohérence est conçue pour répondre à l'intention probable de x!=y et éviter toute confusion avec une expression renvoyant des résultats contenant la valeur interdite/filtrée.

En plus de restreindre la liste dans son ensemble, vous pouvez également faire référence à des entrées de liste spécifiques via l'opérateur d'indexation ([]). Par exemple, vous pouvez utiliser notification_channels[0]:"123" pour tester uniquement le premier élément. Une valeur par défaut (vide, zéro, etc.) est générée dans le cas d'index hors limites.

Conversion implicite en booléen

Lorsqu'une liste est spécifiée dans un filtre sans comparaison binaire, elle est convertie implicitement en booléen. Cette conversion est différente du test visant à vérifier que la liste n'est pas vide. a_list et NOT a_list.empty renvoient des résultats différents pour {false, false, false} ou toute autre liste non vide dont les valeurs sont toutes la valeur booléenne false ou sont implicitement converties en valeur booléenne.

Maps

Propriétés intégrées

Les champs de type carte comportent automatiquement une propriété size générée qui calcule le nombre d'éléments figurant dans cette carte. Par exemple, vous pouvez utiliser user_labels.size dans orderBy pour effectuer un tri par nombre de libellés utilisateur définis. De même, une propriété empty de valeur booléenne est également générée automatiquement.

Remarque : Si votre carte contient une clé nommée size, utilisez user_labels.size pour faire référence au nombre d'éléments dans la carte et utilisez user_labels['size'] pour faire référence à la valeur de la clé de libellé utilisateur size. Il en va de même pour la propriété empty.

Test de l'existence d'une clé

Les cartes peuvent être comparées aux valeurs littérales avec les différents opérateurs binaires compatibles. L'interprétation équivaut logiquement à la projection de la carte dans une liste en extrayant les clés de la carte, puis en exécutant la comparaison. Pour donner un exemple, vous pouvez utiliser user_labels="phase" pour déterminer si la carte user_labels contient une clé dont la valeur est égale à "phase".

Référencer des valeurs par clé

Les entrées de carte peuvent être référencées à l'aide de l'une des deux notations suivantes : notation par points (.) et notation par index ([]). Par exemple, vous pouvez utiliser user_labels.team ou user_labels['team'] pour faire référence à la valeur correspondant à la clé "team" du champ user_labels. Par souci de cohérence avec l'API de métriques qui utilise les préfixes metric.label. et resource.label. plutôt que metric.labels. et resource.labels., les champs de mappage peuvent également être référencés à l'aide du singulier du nom (par exemple, user_label.team est également autorisé). Notez que, pour les clés nommées size ou empty, vous devez utiliser la notation par index. La notation par points fera référence aux propriétés de carte intégrées.

Conversion implicite en booléen

Dans les conversions implicites en valeurs booléennes, une map est considérée comme vraie si elle n'est pas vide et qu'au moins une map *value : est convertie implicitement en true. Cela ne revient pas à effectuer un test vérifiant qu'une carte n'est pas vide.

Trier par type de composé

Tous les champs pouvant être référencés dans un filtre peuvent également l'être dans order_by. Cela s'applique également aux types complexes et composés. L'ordre de tri de ces types est stable et bien défini, mais pas nécessairement intuitif. Cette utilisation est donc déconseillée, mais autorisée.

Listes

Les listes sont comparées à l'aide d'une comparaison lexicographique par élément, la plus petite liste apparaissant en premier si leurs éléments communs sont égaux. Pour donner un exemple, {0, 1} est inférieur à {0, 2}, mais supérieur à {0}.

Maps

Les cartes sont comparées en effectuant une comparaison par élément de leurs valeurs correspondant à l'union de leurs clés. Pour les clés définies dans une carte, mais pas dans l'autre, une valeur par défaut (vide, zéro, etc.) est utilisée pour la comparaison. Pour donner un exemple, {"x":0, "y":0} est inférieur à {"x":1, "y":1}, mais supérieur à {"a":-1} et égal à {}.