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

Referenz: Sortieren und Filtern

In diesem Dokument wird beschrieben, wie Sie die Ergebnisse der entsprechenden Cloud Monitoring API-Befehle sortieren und filtern können. Mit der Sortierung können Sie die Reihenfolge der Elemente in der Ergebnisliste festlegen. Mit Filtern können Sie die Eigenschaften der Elemente definieren, die in die Ergebnisliste aufgenommen werden. Sie verwenden die Felder orderBy und filter, um die API-Antwort zu sortieren und zu filtern.

In der folgenden Tabelle sind die Cloud Monitoring API-Methoden aufgeführt, die das Sortieren oder Filtern unterstützen:

Methode	Unterstützt Sortierung	Unterstützt das Filtern
`projects.alertPolicies.list`	Ja	Ja
`projects.notificationChannels.list`	Ja	Ja
`projects.snoozes.list`	Nein	Ja
`projects.uptimeCheckConfig.list`	Nein	Ja

Grundlagen zum Sortieren und Filtern

Das Vorhandensein der Stringfelder orderBy und filter im Anfragetext der Liste weist auf die Unterstützung für das Sortieren und Filtern in einem list-Vorgang hin. In der API-Referenzdokumentation finden Sie Informationen dazu, ob der Anfragetext diese Felder enthält.

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 :=
       # 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_]*

Filtersyntax

Die Filtersyntax besteht aus einer 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 XYZ“ übereinstimmt:

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

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 :=
       # 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_]*

Unterstützte Felder

Die Felder, auf die in den Feldern filter oder orderBy verwiesen werden kann, hängen vom Typ des aufgelisteten Objekts ab.

`AlertPolicy`

Bei der Aufzählung von AlertPolicy-Objekten kann in filter und orderBy auf die folgenden Felder verwiesen werden:

Name
display_name
documentation.content
documentation.mime_type
user_labels
conditions.size
Kombinator
Aktiviert
notification_channels

`NotificationChannel`

Bei der Aufzählung von NotificationChannel-Objekten kann in filter und orderBy auf die folgenden Felder verwiesen werden:

Name
Typ
display_name
description
labels
user_labels

`UptimeCheckConfig`

Bei der Aufzählung von UptimeCheckConfig-Objekten kann in filter auf die folgenden Felder verwiesen 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

`Snoozes`

Bei der Aufzählung von Snoozes-Objekten kann in filter auf die folgenden Felder verwiesen werden:

interval.start_time
interval.end_time

Themen für Fortgeschrittene

In diesem Abschnitt finden Sie weitere Informationen zum Sortieren und Filtern von API-Ergebnissen.

Feld-Groß-/Kleinschreibung

Feldnamen können sowohl in lower_case_with_underscores- als auch in camelCase-Form angegeben 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 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

Karten können mit Literalwerten mit den verschiedenen unterstützten binären Operatoren 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. Aus Gründen der Konsistenz mit der Metrics API, die die Präfixe metric.label. und resource.label. anstelle von metric.labels. und resource.labels. verwendet, kann auf Kartenfelder auch mit der Singularform des Namens verwiesen werden (z. B. ist user_label.team ebenfalls 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 bool gilt eine Karte als „true“, wenn sie nicht leer ist und mindestens ein *value der Karte 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, können 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 {}.

Referenz: Sortieren und Filtern Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Grundlagen zum Sortieren und Filtern

Syntax der Sortierreihenfolge

Filtersyntax

Beispiele

Formale Spezifikation

Unterstützte Felder

AlertPolicy

NotificationChannel

UptimeCheckConfig

Snoozes

Themen für Fortgeschrittene

Feld-Groß-/Kleinschreibung

Strings

Listen

Maps

Nach zusammengesetzten Typen sortieren

Referenz: Sortieren und Filtern

`AlertPolicy`

`NotificationChannel`

`UptimeCheckConfig`

`Snoozes`