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:
No Console do Cloud, acesse a página Assinaturas.
Clique em Criar assinatura.
Insira o ID da assinatura.
Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
Na seção Filtro de assinatura, insira a expressão de filtro.
Clique em Criar.
Para criar uma assinatura de push com um filtro, siga estas etapas:
No Console do Cloud, acesse a página Assinaturas.
Clique em Criar assinatura.
Insira o ID da assinatura.
Escolha ou crie um tópico no menu suspenso. A assinatura recebe mensagens do tópico.
Na seção Tipo de entrega, clique em Push.
No campo URL do endpoint, Insira o URL do endpoint de push.
Na seção Filtro de assinatura, insira a expressão de filtro.
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
eOR
com parêntesesattributes:"iana.org/language_tag" AND (attributes.domain = "net" OR attributes.domain = "org")
Inválido: operadores
AND
eOR
sem parêntesesattributes:"iana.org/language_tag" AND attributes.domain = "net" OR attributes.domain = "org"
Inválido: os operadores
AND
eOR
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