Dieses Dokument ergänzt die Referenzdokumentation für projects.alertPolicies, projects.notificationChannels und projects.uptimeCheckConfigs in der Cloud Monitoring API.
Sie liefert syntaktische Details zu den Parametern filter und orderBy, wenn sie von der API verwendet werden.
Die folgenden API-Methoden unterstützen die Parameter filter und orderBy:
Die folgende API-Methode unterstützt nur den Parameter filter:
Grundlagen zum Sortieren und Filtern
Die Unterstützung für das Sortieren und Filtern in einem list-Vorgang wird durch das Vorhandensein der Stringfelder filter und orderBy im Anfragetext der Liste angegeben. In der API-Referenzdokumentation finden Sie Informationen dazu, ob der Anfragetext diese Felder enthält. Beide Felder verwenden eine einfache Sprache, um auf die Felder in dem Objekt zu verweisen, das sortiert oder gefiltert wird.
Syntax der Sortierreihenfolge
Das Feld orderBy besteht aus einer durch Kommas getrennten Liste von Feldpfaden, denen optional ein Minuszeichen vorangestellt wird, um die Reihenfolge umzukehren.
Beispielsweise ordnet user_label.team,display_name nach Teamnamen in aufsteigender Reihenfolge und – bei Einträgen mit demselben Team – nach dem Anzeigenamen, ebenfalls in aufsteigender Reihenfolge. Wenn Sie vor einem der durch Kommas getrennten Felder ein Minuszeichen einfügen, wird dieses Feld in absteigender Reihenfolge sortiert. Wenn Sie beispielsweise versuchen, die Ausführlichkeit Ihrer Titel zu reduzieren, können Sie -display_name.size verwenden, um nach Titellänge zu sortieren, wobei die Objekte vom wortreichsten bis zum kürzesten Titel sortiert werden.
Für ein realistischeres Beispiel gruppiert user_label.team,display_name die Ergebnisse zuerst nach Team (in lexikografischer Reihenfolge) und dann innerhalb jeder Teamgruppierung nach dem Titel (auch in lexikografischer Reihenfolge).
Formell kann die Syntax so beschrieben werden:
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_]*
Filtersyntax
Die Filtersyntax besteht aus einer einfachen Ausdruckssprache zum Erstellen eines Prädikats aus einem oder mehreren Feldern der gefilterten Objekte. Negation, Verbindung und Disjunktion werden mit den Keywords NOT, AND und OR geschrieben.
Felder können mithilfe von : (einschließlich), = (gleich), > (größer), < (kleiner als), >= (größer als oder gleich), <= (kleiner oder gleich) und != (ungleich). Die integrierten Funktionen starts_with . ends_with . monitoring.regex.full_match
RE2 sowie die integrierten Attribute empty und size Unterstützung für komplexere Vergleiche.
Beispiele
So geben Sie alle Einträge mit einem nicht leeren Anzeigenamen oder einer Beschreibung zurück, bei denen im Feld user_labels der Schlüssel active (mit einem beliebigen Wert) festgelegt ist:
(NOT display_name.empty OR NOT description.empty) AND user_labels='active'
So geben Sie alle Einträge zurück, deren Beschreibung "cloud" enthält:
description:'cloud'
So geben Sie alle Einträge zurück, deren Titel mit "Temp XXXX" übereinstimmt:
display_name=monitoring.regex.full_match('Temp \\d{4}')
Formale Spezifikation
Die Syntax des Filterausdrucks kann so zusammengefasst werden:
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_]*
Unterstützte Felder
Auf welche Felder in den Feldern filter oder orderBy verwiesen werden kann, hängt vom Typ des aufgelisteten Objekts ab.
AlertPolicy
Auf die folgenden Felder kann in filter und orderBy verwiesen werden, wenn AlertPolicy-Objekte aufgezählt werden:
- name
- display_name
- documentation.content
- documentation.mime_type
- user_labels
- conditions.size
- Kombinator
- Aktiviert
- notification_channels
NotificationChannel
Auf die folgenden Felder kann in filter und orderBy verwiesen werden, wenn NotificationChannel-Objekte aufgezählt werden:
- name
- Typ
- display_name
- description
- labels
- user_labels
UptimeCheckConfig
Auf die folgenden Felder kann in filter verwiesen werden, wenn UptimeCheckConfig-Objekte aufgezählt werden:
- display_name
- user_labels
- selected_regions
- http_check.path
- http_check.headers
- http_check.port
- tcp_check.port
- monitored_resource.type
- monitored_resource.labels
Themen für Fortgeschrittene
Feld-Groß-/Kleinschreibung
Feldnamen können sowohl in lower_case_with_underscores- als auch in camelCase-Formen ausgedrückt werden. Das heißt, sowohl display_name als auch displayName werden unterstützt.
Strings
Integrierte Attribute
Bei Feldern mit Stringwerten wird automatisch die Eigenschaft size generiert, die die Anzahl der Unicode-Zeichen im String berechnet. Dadurch wird beispielsweise ein Filter wie display_name.size > 3 AND display_name.size < 10 aktiviert.
Neben size haben Strings auch eine boolesche empty-Eigenschaft.
Sortierfolge
Beim Auflisten eines Strings in orderBy werden die Strings mithilfe der byteweisen lexikografischen Reihenfolge in der UTF-8-Darstellung des Strings verglichen; die Strings werden nicht nach der Unicode-Sortierreihenfolge sortiert.
implizite boolesche Konvertierung
Es ist möglich, einen String in einem Filter wie in user_label.enabled implizit in einen booleschen Wert zu konvertieren. Beachten Sie, dass diese Konvertierung nicht identisch mit dem Testen ist, ob der String nicht leer ist. Unter dieser Konvertierung wird der Inhalt des Strings in einen booleschen Wert geparst und Strings, die diesen booleschen Wert eindeutig parsen, nehmen diesen Wert an. Wenn der String nicht eindeutig boolesch ist, werden nicht leere Strings als wahr und leere Strings als falsch interpretiert.
Strings, bei denen die Groß- und Kleinschreibung nicht mit "false", "f", "no", "n" oder "0" übereinstimmt, werden als eindeutig falsch eingestuft. Strings, bei denen die Groß- und Kleinschreibung nicht mit "true", "t", "yes", "y" oder "1" übereinstimmt, gelten als eindeutig.
Listen
Integrierte Attribute
Für Felder mit Listenwerten wird automatisch das Attribut size generiert, das die Anzahl der Elemente in dieser Liste berechnet. Beispielsweise können Sie notification_channels.size in orderBy verwenden, um Benachrichtigungsrichtlinien nach der Anzahl der zu benachrichtigenden Channels zu sortieren.
Verwendung in binären Vergleichen
Wenn Sie ein Listenwertfeld mit einem Literal mit einem der verschiedenen binären Operatoren vergleichen, wird der Vergleich so interpretiert, als würde ein elementweiser Vergleich angewendet und dann das ODER der Ergebnisse berechnet. Der Filter notification_channels:"123" ergibt beispielsweise "true", wenn einer der Benachrichtigungskanäle "123" als Teilstring enthält. Speziell für den Operator != wird der Vergleich zwischen Elementen UND und nicht ODER; mit anderen Worten: Für != darf keines der Elemente übereinstimmen. Oder x!=y entspricht logisch dem Pseudocode x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, während x=y logisch dem Pseudocode x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y entspricht. Diese Inkonsistenz wurde entwickelt, um den wahrscheinlichen Intent von x!=y zu beheben und Verwechslungen mit einem Ausdruck zu vermeiden, der Ergebnisse zurückgibt, die den unzulässigen/gefilterten Wert enthalten.
Zusätzlich zur Einschränkung der gesamten Liste können Sie auch über den Indexierungsoperator ([]) auf bestimmte Listeneinträge verweisen. Beispielsweise können Sie mit notification_channels[0]:"123" nur das erste Element testen. Im Fall von Indexen, die außerhalb des gültigen Bereichs liegen, wird ein Standardwert (leer, null usw.) generiert.
Implizite Konvertierung in Bool
Bei Angabe in einem Filter ohne binären Vergleich wird eine Liste implizit in einen booleschen Wert umgewandelt. Diese Conversion unterscheidet sich vom Testen, ob die Liste nicht leer ist. a_list und NOT a_list.empty geben unterschiedliche Ergebnisse für {false, false, false} oder eine andere nicht leere Liste zurück, deren Werte alle implizit in den booleschen Wert false konvertiert werden.
Maps
Integrierte Attribute
Felder mit Kartenwerten haben automatisch eine size-Eigenschaft, die die Anzahl der Elemente in dieser Karte berechnet. Sie können beispielsweise user_labels.size in orderBy verwenden, um nach der Anzahl der definierten Nutzerlabels zu sortieren.
In ähnlicher Weise wird auch eine boolesche Eigenschaft empty automatisch generiert.
Auf Schlüsselexistenz testen
Zuordnungen können über die verschiedenen unterstützten Binäroperatoren mit Literalwerten verglichen werden. Die Interpretation entspricht logisch der Projektion der Karte in eine Liste, indem die Schlüssel der Karte extrahiert und dann der Vergleich ausgeführt wird.
Als Beispiel können Sie mit user_labels="phase" ermitteln, ob die user_labels-Zuordnung einen Schlüssel enthält, dessen Wert gleich "Phase" ist.
Werte nach Schlüssel referenzieren
Auf Karteneinträge kann mit einer von zwei Notationen verwiesen werden: Punkt (.) und Index ([]). Sie können beispielsweise user_labels.team oder user_labels['team'] verwenden, um auf den Wert zu verweisen, der dem Schlüssel "team" im Feld user_labels entspricht. Damit die Messwert-API die Präfixe metric.label. und resource.label. anstelle von metric.labels. und resource.labels. verwendet, können Zuordnungsfelder auch im Singular des Namens referenziert werden (z. B. ist auch user_label.team zulässig).
Beachten Sie, dass Sie bei Schlüsseln mit dem Namen size oder empty die Indexnotation verwenden müssen. Bei Verwendung der Punktnotation wird auf die integrierten Kartenattribute Bezug genommen.
Implizite Konvertierung in Bool
Bei impliziten Konvertierungen in den booleschen Wert wird eine Zuordnung als „true“ betrachtet, wenn sie nicht leer ist und mindestens ein Zuordnungswert (*value) implizit in „true“ konvertiert wird. Dies entspricht nicht dem Testen, ob die Karte nicht leer ist.
Nach zusammengesetzten Typen sortieren
Alle Felder, auf die in einem Filter verwiesen werden kann, kann auch in order_by referenziert werden. Dies gilt auch für komplexe und zusammengesetzte Typen. Die Sortierreihenfolge für diese Typen ist stabil und klar definiert, aber nicht unbedingt intuitiv. Daher wird von dieser Verwendung abgeraten, sie ist jedoch zulässig.
Listen
Listen werden mithilfe eines lexikografischen Elements verglichen, wobei die kleinere Liste zuerst folgt, wenn die gemeinsamen Elemente gleich sind.
Ein Beispiel: {0, 1} ist kleiner als {0, 2}, aber größer als {0}.
Maps
Karten werden miteinander verglichen, indem die Kartenwerte, die der Vereinigung ihrer Schlüssel entsprechen, auf Elementbasis verglichen werden. Für Schlüssel, die in einer Zuordnung, aber nicht in der anderen definiert sind, wird ein Standardwert (leer, null usw.) für den Vergleich verwendet.
Beispiel: {"x":0, "y":0} ist kleiner als {"x":1, "y":1}, aber größer als {"a":-1} und ist gleich {}.