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