Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Riferimento: ordinamento e filtri

Questo documento descrive come ordinare e filtrare i risultati dei comandi dell'API Cloud Monitoring applicabili. L'ordinamento ti consente di specificare l'ordine degli elementi nell'elenco dei risultati. Il filtro ti consente di definire le proprietà degli elementi inclusi nell'elenco dei risultati. Utilizzi i campi orderBy e filter per ordinare e filtrare la risposta dell'API.

La tabella seguente elenca i metodi dell'API Cloud Monitoring che supportano l'ordinamento o il filtraggio:

Metodo	Supporta l'ordinamento	Supporta il filtraggio
`projects.alertPolicies.list`	Sì	Sì
`projects.notificationChannels.list`	Sì	Sì
`projects.snoozes.list`	No	Sì
`projects.uptimeCheckConfig.list`	No	Sì

Nozioni di base su ordinamento e filtri

La presenza dei campi stringa orderBy e filter nel corpo della richiesta di elenco indica il supporto per l'ordinamento e il filtraggio in un'operazione list. Consulta la documentazione di riferimento dell'API per determinare se il corpo della richiesta include questi campi.

Sintassi dell'ordinamento

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

Ad esempio, user_label.team,display_name ordina per nome della squadra in ordine crescente e poi, per le voci con la stessa squadra, ordina per 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 la verbosità dei titoli, puoi utilizzare -display_name.size per ordinare in base alla lunghezza del titolo, con gli oggetti ordinati dal titolo più prolisso a quello più breve.

Per fornire un esempio più realistico, i gruppi user_label.team,display_name organizzano i risultati prima per squadra (in ordine lessicografico) e poi, all'interno di ogni squadra raggruppamento, li organizzano per titolo (sempre in ordine lessicografico).

Formalmente, la sintassi può essere descritta come:

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

Sintassi filtro

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

Esempi

Per restituire tutte le voci con un nome visualizzato o una descrizione non vuoti in cui il campo user_labels ha impostato la chiave active (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 XYZ":

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

Specifiche formali

La sintassi dell'espressione 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 :=
       # 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_]*

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:

nome
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:

nome
tipo
display_name
descrizione
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

`Snoozes`

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

interval.start_time
interval.end_time

Argomenti avanzati

Questa sezione fornisce ulteriori informazioni sull'ordinamento e il filtraggio dei risultati dell'API.

Rivestimento del campo

I nomi dei campi possono essere espressi sia in formato lower_case_with_underscores che in formato camelCase. ovvero sono supportati sia display_name che displayName.

Stringhe

Proprietà integrate

I campi con valori stringa hanno automaticamente una proprietà size generata che calcola il numero di caratteri Unicode nella stringa. In questo modo è possibile, ad esempio, utilizzare un filtro come display_name.size > 3 AND display_name.size < 10. Oltre a size, le stringhe hanno anche una proprietà booleana empty.

Ordinamento

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

Conversione booleana implicita

È possibile convertire implicitamente una stringa in un valore booleano in un filtro come in user_label.enabled. Tieni presente che questa conversione non è identica al test che verifica che la stringa non sia vuota. In questa conversione, i contenuti della stringa vengono analizzati in un valore booleano e le stringhe che vengono analizzate in modo non ambiguo in un valore booleano assumono quel valore. Se la stringa non è ovviamente un valore booleano, le stringhe non vuote vengono interpretate come true e le stringhe vuote vengono interpretate come false.

Le stringhe che corrispondono a "false", "f", "no", "n" o "0" senza distinzione tra maiuscole e minuscole sono considerate inequivocabilmente false; le stringhe che corrispondono a "true", "t", "yes", "y" o "1" senza distinzione tra maiuscole e minuscole sono considerate inequivocabilmente vere.

Elenchi

Proprietà integrate

I campi con valori di elenco hanno automaticamente una proprietà size generata che calcola il numero di elementi nell'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 si confronta un campo con valori di elenco con un valore letterale utilizzando uno dei vari operatori binari, il confronto viene interpretato come l'applicazione di un confronto elemento per elemento e il calcolo dell'OR dei risultati. Ad esempio, il filtro notification_channels:"123" restituirà true se uno qualsiasi dei canali di notifica contiene "123" come sottostringa. Per l'operatore !=, in particolare, il confronto elemento per elemento viene eseguito con AND anziché con OR; in altre parole, per !=, non è consentita la corrispondenza di alcun elemento. In altre parole, x!=y è logicamente equivalente allo pseudocodice x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, mentre x=y è logicamente equivalente allo pseudocodice x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Questa incoerenza è progettata per rispondere alla probabile intenzione di x!=y ed evitare confusione con un'espressione che restituisce risultati contenenti il valore filtrato.

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

Conversione implicita in booleano

Se specificato in un filtro senza un confronto binario, un elenco verrà convertito implicitamente in booleano. Questa conversione è diversa dal test che verifica 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 o vengono convertiti implicitamente nel valore booleano false.

Maps

Proprietà integrate

I campi con valori di mappa hanno automaticamente una proprietà size generata 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.

Testare l'esistenza della chiave

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

Fare riferimento ai valori per chiave

È possibile fare riferimento alle voci della mappa utilizzando una delle due notazioni: punto (.) e 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 della 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; l'utilizzo della notazione con il punto fa riferimento alle proprietà della mappa integrate.

Conversione implicita in booleano

Nelle conversioni implicite in booleano, una mappa viene considerata true se non è vuota e almeno un valore della mappa viene convertito implicitamente in true. Non è la stessa cosa di verificare che la mappa non sia vuota.

Ordinamento per tipi composti

Tutti i campi a cui è possibile fare riferimento in un filtro possono essere utilizzati anche 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 elemento per elemento, con l'elenco più piccolo che viene visualizzato per primo nel caso in cui gli elementi comuni siano uguali. Ad esempio, {0, 1} è inferiore a {0, 2} ma maggiore di {0}.

Maps

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

Riferimento: ordinamento e filtri Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Nozioni di base su ordinamento e filtri

Sintassi dell'ordinamento

Sintassi filtro

Esempi

Specifiche formali

Campi supportati

AlertPolicy

NotificationChannel

UptimeCheckConfig

Snoozes

Argomenti avanzati

Rivestimento del campo

Stringhe

Elenchi

Maps

Ordinamento per tipi composti

Riferimento: ordinamento e filtri

`AlertPolicy`

`NotificationChannel`

`UptimeCheckConfig`

`Snoozes`