Riferimento: ordinamento e filtri

Questo documento integra la documentazione di riferimento per projects.alertPolicies, projects.notificationChannels e projects.uptimeCheckConfigs nell'API Cloud Monitoring. Fornisce dettagli sintattici sui parametri filter e orderBy quando utilizzato dall'API.

I seguenti metodi API supportano i parametri filter e orderBy:

Il seguente metodo API supporta solo il parametro filter:

Nozioni di base su ordinamento e filtri

Il supporto per l'ordinamento e i filtri in un'operazione list è indicato dalla presenza di campi stringa filter e orderBy nel corpo della richiesta dell'elenco (consulta la documentazione di riferimento dell'API per verificare se il corpo della richiesta contiene questi campi). Entrambi i campi utilizzano un linguaggio semplice per fare riferimento ai campi dell'oggetto che viene ordinato o filtrato.

Sintassi di ordinamento

Il campo orderBy è costituito da un elenco separato da virgole di percorsi dei campi che sono facoltativamente preceduti dal segno meno per invertire l'ordine.

Ad esempio, user_label.team,display_name ordina in base al nome del team in ordine crescente e poi, per le voci con lo stesso team, ordina in base al nome visualizzato, sempre in ordine crescente. Se aggiungi un segno meno davanti a uno dei campi separati da virgole, il campo viene ordinato in ordine decrescente. Ad esempio, se stai cercando di ridurre il livello di dettaglio dei titoli, puoi utilizzare -display_name.size per ordinare in base alla lunghezza del titolo, con gli oggetti ordinati dal titolo più conciso a quello più breve.

Per fornire un esempio più realistico, user_label.team,display_name raggruppa i risultati prima per team (in ordine lessicografico) e poi, all'interno di ogni team, raggruppa i risultati per titolo (anche in ordine lessicografico).

Formalmente, la sintassi può essere descritta come segue:

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

Sintassi dei filtri

La sintassi dei filtri è costituita da un semplice linguaggio di espressione per creare un predicato da uno o più campi degli oggetti filtrati. La negazione, la congiunzione e la disgiunzione vengono scritte utilizzando le parole chiave NOT, AND e OR. I campi possono essere confrontati con i valori letterali utilizzando gli operatori : (contenimento), = (uguaglianza), > (maggiore), < (minore di), >= (maggiore o uguale a), <= (minore o uguale a) e != (disuguaglianza). Le funzioni integrate starts_with, ends_with, monitoring.regex.full_match (sintassi RE2), così come le proprietà integrate empty e size, forniscono supporto per confronti più avanzati.

Esempi

Per restituire tutte le voci con una descrizione o un nome visualizzato non vuoto in cui il campo user_labels ha la chiave active impostata (con qualsiasi valore):

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

Per restituire tutte le voci la cui descrizione contiene "cloud":

description:'cloud'

Per restituire tutte le voci il cui titolo corrisponde a "Temp XXXX":

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

Specifiche formali

La sintassi delle espressioni di filtro può essere riassunta come segue:

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

Campi supportati

I campi a cui è possibile fare riferimento nei campi filter o orderBy dipendono dal tipo di oggetto elencato.

AlertPolicy

È possibile fare riferimento ai seguenti campi in filter e orderBy durante l'enumerazione degli oggetti AlertPolicy:

  • name
  • display_name
  • documentation.content
  • documentation.mime_type
  • user_labels
  • conditions.size
  • combinatore
  • abilitato
  • notification_channels

NotificationChannel

È possibile fare riferimento ai seguenti campi in filter e orderBy durante l'enumerazione degli oggetti NotificationChannel:

  • name
  • tipo
  • display_name
  • description
  • etichette
  • user_labels

UptimeCheckConfig

È possibile fare riferimento ai seguenti campi in filter durante l'enumerazione degli oggetti 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

Argomenti avanzati

Maiuscole/minuscole nel campo

I nomi dei campi possono essere espressi nei formati lower_case_with_underscores e camelCase. Ciò significa che sono supportati sia display_name sia displayName.

Corde

Proprietà integrate

Nei campi con valori stringa viene generata automaticamente una proprietà size che calcola il numero di caratteri Unicode nella stringa. Questo abilita, ad esempio, un filtro come display_name.size > 3 AND display_name.size < 10. Oltre a size, le stringhe hanno anche una proprietà bool empty.

Ordinamento

Quando si elenca una stringa in orderBy, le stringhe vengono confrontate utilizzando l'ordinamento lessicografico per byte nella rappresentazione UTF-8 della stringa; le stringhe non vengono ordinate in base all'ordine di confronto Unicode.

Conversione bool implicita

È possibile convertire implicitamente una stringa in bool in un filtro come in user_label.enabled. Tieni presente che questa conversione non è identica a verificare che la stringa non sia vuota; in base a questa conversione, i contenuti della stringa vengono analizzati come bool e le stringhe che analizzano in modo inequivocabile come un valore booleano di quel valore booleano. Se la stringa non ha un valore booleano evidentemente, le stringhe non vuote vengono interpretate come vere e le stringhe vuote vengono interpretate come false.

Le stringhe che corrispondono senza distinzione tra maiuscole e minuscole a "false", "f", "no", "n" o "0" vengono considerate false in modo inequivocabile. Le stringhe che corrispondono a "true", "t", "yes", "y" o "1" senza distinzione tra maiuscole e minuscole vengono considerate vere senza ambiguità.

Elenchi

Proprietà integrate

Ai campi con valori dell'elenco viene generata automaticamente una proprietà size che calcola il numero di elementi in quell'elenco. Ad esempio, puoi utilizzare notification_channels.size in orderBy per ordinare i criteri di avviso in base al numero di canali a cui inviano notifiche.

Utilizzo nei confronti binari

Quando confronti un campo con valori in base all'elenco e un valore letterale con uno dei vari operatori binari, il confronto viene interpretato come l'applicazione di un confronto tra elementi e il conseguente calcolo dell'OR dei risultati. Ad esempio, il filtro notification_channels:"123" restituirà il valore true se uno qualsiasi dei canali di notifica ha "123" come sottostringa. Per l'operatore !=, in particolare, il confronto a livello di elemento viene applicato tramite AND anziché OR; in altre parole, per !=, nessuno degli elementi può corrispondere. Oppure, per ribadire, x!=y è logicamente equivalente allo pseudo-codice x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, mentre x=y è logicamente equivalente allo pseudo-codice x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Questa incoerenza è progettata per risolvere il probabile intent di x!=y e impedire confusione con un'espressione di questo tipo che restituisce risultati contenenti il valore vietato/filtrato.

Oltre a limitare l'elenco nel suo complesso, è anche possibile fare riferimento a voci specifiche dell'elenco tramite l'operatore di indicizzazione ([]). Ad esempio, puoi utilizzare notification_channels[0]:"123" per testare solo il primo elemento. In caso di indici fuori intervallo viene generato un valore predefinito (vuoto, zero e così via).

Conversione implicita in bool

Se specificato in un filtro senza un confronto binario, un elenco verrà convertito implicitamente in booleano. Questa conversione è diversa dal verificare che l'elenco non sia vuoto; a_list e NOT a_list.empty restituiscono risultati diversi per {false, false, false} o qualsiasi altro elenco non vuoto i cui valori sono tutti o vengono implicitamente convertiti nel valore booleano false.

Maps

Proprietà integrate

Ai campi con valori della mappa viene generata automaticamente una proprietà size che calcola il numero di elementi nella mappa. Ad esempio, puoi utilizzare user_labels.size in orderBy per ordinare in base al numero di etichette utente definite. Analogamente, viene generata automaticamente anche una proprietà empty con valore booleano.

Verificare l'esistenza di una chiave

Le mappe possono essere confrontate con valori letterali con i vari operatori binari supportati. L'interpretazione è logicamente equivalente alla proiezione della mappa in un elenco estraendo le relative chiavi e quindi eseguendo il confronto. Per fare un esempio, puoi utilizzare user_labels="phase" per determinare se la mappa user_labels contiene una chiave il cui valore è uguale a "phase".

Riferimento dei valori per chiave

È possibile fare riferimento alle voci della mappa utilizzando una delle due notazioni: notazione del punto (.) e notazione dell'indice ([]). Ad esempio, puoi utilizzare user_labels.team o user_labels['team'] per fare riferimento al valore corrispondente alla chiave "team" nel campo user_labels. Per coerenza con l'API delle metriche che utilizza i prefissi metric.label. e resource.label. anziché metric.labels. e resource.labels., è possibile fare riferimento anche ai campi mappa utilizzando la forma singolare del nome (ad esempio, è consentito anche user_label.team). Tieni presente che, per le chiavi denominate size o empty, devi utilizzare la notazione dell'indice; la notazione dei punti riguarderà le proprietà integrate delle mappe.

Conversione implicita in bool

Nelle conversioni implicite in bool, una mappa viene considerata vera se non è vuota e almeno un *value di una mappa viene convertito implicitamente in true. Non è come verificare che la mappa non sia vuota.

Ordinamento per tipi composti

È possibile fare riferimento anche a tutti i campi a cui è possibile fare riferimento in un filtro in order_by. Questo vale anche per i tipi complessi e composti. L'ordinamento per questi tipi è stabile e ben definito, anche se non necessariamente intuitivo; pertanto, questo utilizzo è sconsigliato, ma consentito.

Elenchi

Gli elenchi vengono confrontati utilizzando un confronto lessicografico a livello di elemento. L'elenco più piccolo viene visualizzato per primo se gli elementi comuni sono uguali. Per fare un esempio, {0, 1} è inferiore a {0, 2} ma maggiore di {0}.

Maps

Le mappe vengono confrontate eseguendo un confronto a livello di elemento dei valori delle mappe corrispondenti all'unione delle relative chiavi. Per le chiavi definite in una mappa ma non nell'altra, per il confronto viene utilizzato un valore predefinito (vuoto, zero e così via). Per fare un esempio, {"x":0, "y":0} è minore di {"x":1, "y":1} ma maggiore di {"a":-1} e uguale a {}.