Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como filtrar mensagens

Nesta página, explicamos como criar assinaturas com filtros.

Ao receber mensagens de uma assinatura com um filtro, você recebe apenas as mensagens que correspondem ao filtro. O serviço Pub/Sub reconhece automaticamente as mensagens que não correspondem ao filtro. É possível filtrar mensagens pelos atributos.

Quando você recebe mensagens de uma assinatura com um filtro, não há taxas de saída para as mensagens que o Pub/Sub confirma automaticamente. Sujeito a taxas de entrega de mensagens e taxas de armazenamento relacionadas à busca para essas mensagens.

Como criar assinaturas com filtros

As assinaturas de pull e push podem ter filtros. Todos os assinantes podem receber mensagens de assinaturas com filtros, incluindo assinantes que usam a API StreamingPull.

É possível criar uma assinatura com um filtro usando o Console do Cloud, a ferramenta de linha de comando gcloud ou a API Pub/Sub.

Console

Para criar uma assinatura de pull com um filtro, siga estas etapas:

  1. No Console do Cloud, acesse a página Assinaturas.

    Acessar a página "Assinaturas"

  2. Clique em Criar assinatura.

  3. Insira o ID da assinatura.

  4. Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.

  5. Na seção Filtro de assinatura, insira a expressão de filtro.

  6. Clique em Criar.

Para criar uma assinatura de push com um filtro, siga estas etapas:

  1. No Console do Cloud, acesse a página Assinaturas.

    Acessar a página "Assinaturas"

  2. Clique em Criar assinatura.

  3. Insira o ID da assinatura.

  4. Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.

  5. Na seção Tipo de entrega, clique em Push.

  6. No campo URL do endpoint, Insira o URL do endpoint de push.

  7. Na seção Filtro de assinatura, insira a expressão de filtro.

  8. Clique em Criar.

gcloud

Para criar uma assinatura de pull com um filtro, use o comando gcloud pubsub subscriptions create com a sinalização --message-filter:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --message-filter='FILTER'

Substitua:

  • SUBSCRIPTION_ID: o ID da assinatura a ser criada
  • TOPIC_ID: o ID do tópico a ser anexado à assinatura
  • FILTER: uma expressão na sintaxe de filtragem

Para criar uma assinatura de push com um filtro, use o comando gcloud pubsub subscriptions create com as sinalizações --push-endpoint e --message-filter:

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --push-endpoint=PUSH_ENDPOINT \
  --message-filter='FILTER'

Substitua:

  • SUBSCRIPTION_ID: o ID da assinatura a ser criada
  • TOPIC_ID: o ID do tópico a ser anexado à assinatura
  • PUSH_ENDPOINT: o URL do servidor em que o assinante de push é executado
  • FILTER: uma expressão na sintaxe de filtragem

REST

Para criar uma assinatura com um filtro, use o método projects.subscriptions.create.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Substitua:

  • PROJECT_ID: o ID do projeto para criar a assinatura
  • SUBSCRIPTION_ID: o ID da assinatura a ser criada

Para criar uma assinatura de pull com um filtro, especifique o filtro no corpo da solicitação:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "filter": "FILTER"
}

Substitua:

  • PROJECT_ID: o ID do projeto com o tópico
  • TOPIC_ID: o ID do tópico a ser anexado à assinatura
  • FILTER: uma expressão na sintaxe de filtragem

Para criar uma assinatura de push com um filtro, especifique o endpoint de push e o filtro no corpo da solicitação:

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "pushConfig": {
    "pushEndpoint": "PUSH_ENDPOINT"
  },
  "filter": "FILTER"
}

Substitua:

  • PROJECT_ID: o ID do projeto com o tópico
  • TOPIC_ID: o ID do tópico a ser anexado à assinatura
  • PUSH_ENDPOINT: o URL do servidor em que o assinante de push é executado
  • FILTER: uma expressão na sintaxe de filtragem

O comprimento máximo de um filtro é 256 bytes. Depois de criar a assinatura, não será possível modificar o filtro. As métricas de backlog podem incluir mensagens que não correspondem ao filtro.

Sintaxe de filtragem

Para filtrar mensagens, escreva uma expressão que opere em atributos. É possível escrever uma expressão que corresponda à chave ou ao valor dos atributos. O identificador attributes seleciona os atributos na mensagem.

Por exemplo, os filtros na tabela a seguir selecionam o atributo domain:

Filtro Descrição
attributes:domain Mensagens com o atributo domain
NOT attributes:domain Mensagens sem o atributo domain
attributes.domain = "com" Mensagens com o atributo domain e o valor de com
attributes.domain != "com" Mensagens sem o atributo domain e o valor de com
hasPrefix(attributes.domain, "co") Mensagens com o atributo domain e um valor que começa com co
NOT hasPrefix(attributes.domain, "co") Mensagens sem o atributo domain e um valor que começa com co

Operadores de comparação

Filtre os atributos com os seguintes operadores de comparação:

  • :
  • =
  • !=

O operador : corresponde a uma chave em uma lista de atributos.

attributes:KEY

Os operadores de igualdade correspondem a chaves e valores. O valor precisa ser um literal de string.

attributes.KEY = "VALUE"

Uma expressão com um operador de igualdade precisa começar com uma chave, e ele precisa comparar uma chave e um valor.

  • Válido: o filtro compara uma chave e um valor.

    attributes.domain = "com"

  • Inválido: o lado esquerdo do filtro é um valor.

    "com" = attributes.domain

  • Inválido: o filtro compara duas chaves

    attributes.domain = attributes.website

A chave e o valor diferenciam maiúsculas de minúsculas e precisam corresponder exatamente ao atributo. Se uma chave contiver caracteres diferentes de hifens, sublinhados ou caracteres alfanuméricos, use um literal de string.

attributes."iana.org/language_tag" = "en"

Para usar barras invertidas, aspas e caracteres não imprimíveis em um filtro, faça o escape dos caracteres de um literal de string. Também é possível usar sequências Unicode, hexadecimais e octais em um literal de string.

  • Válido: filtra os caracteres de escape dentro de um literal de string

    attributes:"\u307F\u3093\u306A"

  • Inválido: o filtro faz o escape de caracteres sem um literal de string

    attributes:\u307F\u3093\u306A

Operadores booleanos

É possível usar operadores booleanos em um filtro. Por exemplo, o filtro a seguir é para mensagens com o atributo iana.org/language_tag, mas sem o atributo domain e o valor com.

attributes:"iana.org/language_tag" AND NOT attributes.domain = "com"

O operador NOT tem a precedência mais alta. Para combinar os operadores AND e OR, use parênteses e expressões completas.

  • Válido: operadores AND e OR com parênteses

    attributes:"iana.org/language_tag" AND (attributes.domain = "net" OR attributes.domain = "org")

  • Inválido: operadores AND e OR sem parênteses

    attributes:"iana.org/language_tag" AND attributes.domain = "net" OR attributes.domain = "org"

  • Inválido: os operadores AND e OR combinam expressões incompletas.

    attributes.domain = "com" AND ("net" OR "org")

Você também pode usar o operador menos unário em vez do operador NOT.

attributes.domain = "com" AND -attributes:"iana.org/language_tag"

Funções

A função hasPrefix filtra atributos com valores que começam com uma substring.

hasPrefix(attributes.KEY, "SUBSTRING")

Substitua:

  • KEY: o nome do atributo
  • SUBSTRING: uma substring do valor