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

Referência: ordenação e filtragem

Este documento descreve como pode ordenar e filtrar os resultados dos comandos da API Cloud Monitoring aplicáveis. A ordenação permite-lhe especificar a ordem dos elementos na lista de resultados. A filtragem permite-lhe definir as propriedades dos elementos que estão incluídos na lista de resultados. Use os campos orderBy e filter para ordenar e filtrar a resposta da API.

A tabela seguinte lista os métodos da API Cloud Monitoring que suportam a ordenação ou a filtragem:

Método	Suporta ordenação	Suporta filtragem
`projects.alertPolicies.list`	Sim	Sim
`projects.notificationChannels.list`	Sim	Sim
`projects.snoozes.list`	Não	Sim
`projects.uptimeCheckConfig.list`	Não	Sim

Noções básicas de ordenação e filtragem

A presença de campos de strings orderBy e filter no corpo do pedido de lista indica suporte para ordenação e filtragem numa operação list. Consulte a documentação de referência da API para determinar se o corpo do pedido inclui estes campos.

Sintaxe de ordenação

O campo orderBy consiste numa lista de caminhos de campos separados por vírgulas que têm opcionalmente um sinal de subtração como prefixo para inverter a ordem.

Por exemplo, user_label.team,display_name as encomendas por nome da equipa em ordem ascendente e, em seguida, para as entradas com a mesma equipa, as encomendas por nome a apresentar, também em ordem ascendente. Se adicionar um sinal de subtração antes de um dos campos separados por vírgulas, esse campo é ordenado por ordem descendente. Por exemplo, se estiver a tentar reduzir a verbosidade dos títulos, pode usar -display_name.size para ordenar por comprimento do título, com os objetos ordenados do título mais detalhado para o título mais breve.

Para dar um exemplo mais realista, o user_label.team,display_name agrupa primeiro os resultados por equipa (por ordem lexicográfica) e, em seguida, dentro de cada grupo de equipas, organiza os resultados pelo título (também por ordem lexicográfica).

Formalmente, a sintaxe pode ser descrita como:

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

Sintaxe do filtro

A sintaxe do filtro consiste numa linguagem de expressão para criar um predicado a partir de um ou mais campos dos objetos que estão a ser filtrados. A negação, a conjunção e a disjunção são escritas com as palavras-chave NOT, AND e OR. Os campos podem ser comparados com valores literais através dos operadores : (contém), = (igual a), > (maior que), < (inferior a), >= (maior ou igual a), <= (inferior ou igual a) e != (diferente de). As funções incorporadas starts_with, ends_with e monitoring.regex.full_match (sintaxe RE2), bem como as propriedades incorporadas empty e size, oferecem suporte para comparações mais avançadas.

Exemplos

Para devolver todas as entradas com um nome a apresentar ou uma descrição não vazios em que o campo user_labels tem a chave active definida (com qualquer valor):

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

Para devolver todas as entradas cuja descrição contenha "nuvem":

description:'cloud'

Para devolver todas as entradas cujo título corresponda a "Temp XYZ":

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

Especificação formal

A sintaxe da expressão de filtro pode ser resumida da seguinte forma:

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

Campos suportados

Os campos que podem ser referenciados nos campos filter ou orderBy dependem do tipo de objeto que está a ser listado.

`AlertPolicy`

Os seguintes campos podem ser referenciados em filter e orderBy quando enumerar objetos AlertPolicy:

nome
display_name
documentation.content
documentation.mime_type
user_labels
conditions.size
combinador
ativada
notification_channels

`NotificationChannel`

Os seguintes campos podem ser referenciados em filter e orderBy quando enumerar objetos NotificationChannel:

nome
escrever
display_name
descrição
etiquetas
user_labels

`UptimeCheckConfig`

Os seguintes campos podem ser referenciados em filter quando enumerar UptimeCheckConfig objetos:

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`

Os seguintes campos podem ser referenciados em filter quando enumerar Snoozes objetos:

interval.start_time
interval.end_time

Tópicos avançados

Esta secção fornece mais informações sobre a ordenação e a filtragem dos resultados da API.

Caixa do campo

Os nomes dos campos podem ser expressos nas formas lower_case_with_underscores e camelCase. Ou seja, display_name e displayName são suportados.

Strings

Propriedades integradas

Os campos com valor de string têm automaticamente uma propriedade size gerada que calcula o número de carateres Unicode na string. Isto permite, por exemplo, um filtro como display_name.size > 3 AND display_name.size < 10. Além de size, as strings também têm uma propriedade bool empty.

Ordem de ordenação

Quando lista uma string em orderBy, as strings são comparadas através da ordenação lexicográfica por bytes na representação UTF-8 da string. As strings não são ordenadas de acordo com a ordem de intercalação Unicode.

Conversão booleana implícita

É possível converter implicitamente uma string em bool num filtro, como em user_label.enabled. Tenha em atenção que esta conversão não é idêntica ao teste de que a string não está vazia. Nesta conversão, o conteúdo da string é analisado para um valor booleano e as strings que são analisadas de forma inequívoca para um valor booleano assumem esse valor booleano. Se a string não for obviamente um valor booleano, as strings não vazias são interpretadas como verdadeiras e as strings vazias são interpretadas como falsas.

As strings que correspondem a "false", "f", "no", "n" ou "0" sem distinção entre maiúsculas e minúsculas são consideradas inequivocamente falsas; as strings que correspondem a "true", "t", "yes", "y" ou "1" sem distinção entre maiúsculas e minúsculas são consideradas inequivocamente verdadeiras.

Listas

Propriedades integradas

Os campos com valores de lista têm automaticamente uma propriedade size gerada que calcula o número de elementos nessa lista. Por exemplo, pode usar notification_channels.size em orderBy para ordenar as políticas de alerta pelo número de canais que notificam.

Use em comparações binárias

Quando compara um campo com valor de lista a um literal com um dos vários operadores binários, a comparação é interpretada como a aplicação de uma comparação elemento a elemento e, em seguida, o cálculo do OU dos resultados. Por exemplo, o filtro notification_channels:"123" é avaliado como verdadeiro se qualquer um dos canais de notificação tiver "123" como uma substring. Especificamente, para o operador !=, a comparação ao nível dos elementos é ANDed e não ORed. Por outras palavras, para !=, nenhum dos elementos pode corresponder. Em alternativa, para reformular, x!=y é logicamente equivalente ao pseudocódigo x[0]!=y AND x[1]!=y AND ... AND x[x.size-1]!=y, enquanto x=y é logicamente equivalente ao pseudocódigo x[0]=y OR x[1]=y OR ... OR x[x.size-1]=y. Esta inconsistência destina-se a abordar a provável intenção de x!=y e evitar a confusão com uma expressão que devolve resultados que contêm o valor filtrado.

Além de restringir a lista como um todo, também é possível fazer referência a entradas específicas da lista através do operador de indexação ([]). Por exemplo, pode usar notification_channels[0]:"123" para testar apenas o primeiro elemento. É gerado um valor predefinido (vazio, zero, etc.) no caso de índices fora dos limites.

Conversão implícita em bool

Quando especificada num filtro sem uma comparação binária, uma lista é convertida implicitamente em booleano. Esta conversão é diferente do teste que verifica se a lista não está vazia; a_list e NOT a_list.empty devolvem resultados diferentes para {false, false, false} ou qualquer outra lista não vazia cujos valores sejam todos ou sejam convertidos implicitamente no valor booleano false.

Maps

Propriedades integradas

Os campos com valores de mapa têm automaticamente uma propriedade size gerada que calcula o número de elementos nesse mapa. Por exemplo, pode usar user_labels.size em orderBy para ordenar pelo número de etiquetas de utilizador definidas. Da mesma forma, uma propriedade empty com valor booleano também é gerada automaticamente.

Testar a existência de chaves

Os mapas podem ser comparados com valores literais com os vários operadores binários suportados. A interpretação é logicamente equivalente a projetar o mapa numa lista extraindo as chaves do mapa e, em seguida, executando a comparação. Por exemplo, pode usar user_labels="phase" para determinar se o mapa user_labels contém uma chave cujo valor é igual a "phase".

Referenciar valores por chave

As entradas de mapas podem ser referenciadas através de uma de duas notações: notação de ponto (.) e notação de índice ([]). Por exemplo, pode usar user_labels.team ou user_labels['team'] para se referir ao valor correspondente à chave "equipa" no campo user_labels. Para manter a consistência com a API de métricas, que usa os prefixos metric.label. e resource.label. em vez de metric.labels. e resource.labels., também é possível fazer referência aos campos de mapas usando a forma singular do nome (por exemplo, user_label.team também é permitido). Tenha em atenção que, para chaves com o nome size ou empty, tem de usar a notação de índice. Se usar a notação de ponto, vai referir-se às propriedades do mapa incorporadas.

Conversão implícita em bool

Nas conversões implícitas para bool, um mapa é considerado verdadeiro se não estiver vazio e, pelo menos, um valor do mapa for convertido implicitamente em verdadeiro. Isto não é o mesmo que testar se o mapa não está vazio.

Ordenação por tipos compostos

Todos os campos que podem ser referenciados num filtro também podem ser referenciados em order_by. Isto também se aplica a tipos complexos e compostos. A ordem de ordenação destes tipos é estável e bem definida, embora não seja necessariamente intuitiva. Por conseguinte, esta utilização é desaconselhada, mas permitida.

Listas

As listas são comparadas através de uma comparação lexicográfica elemento a elemento, com a lista mais pequena a aparecer primeiro no caso de os respetivos elementos comuns serem iguais. Por exemplo, {0, 1} é inferior a {0, 2}, mas superior a {0}.

Maps

Os mapas são comparados através de uma comparação elemento a elemento dos valores do mapa correspondentes à união das respetivas chaves. Para as chaves definidas num mapa, mas não no outro, é usado um valor predefinido (vazio, zero, etc.) para a comparação. Por exemplo, {"x":0, "y":0} é inferior a {"x":1, "y":1}, mas superior a {"a":-1} e igual a {}.

Referência: ordenação e filtragem Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Noções básicas de ordenação e filtragem

Sintaxe de ordenação

Sintaxe do filtro

Exemplos

Especificação formal

Campos suportados

AlertPolicy

NotificationChannel

UptimeCheckConfig

Snoozes

Tópicos avançados

Caixa do campo

Strings

Listas

Maps

Ordenação por tipos compostos

Referência: ordenação e filtragem

`AlertPolicy`

`NotificationChannel`

`UptimeCheckConfig`

`Snoozes`