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