Nesta página, explicamos como criar assinaturas do Pub/Sub 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 as mensagens pelos atributos delas, mas não pelos dados.
É possível ter várias assinaturas anexadas a um tópico, e cada uma delas pode ter um filtro diferente.
Por exemplo, se você tiver um tópico que recebe notícias de diferentes partes do mundo, é possível configurar uma assinatura para filtrar notícias que são publicadas apenas de uma região específica. Para essa configuração, você precisa garantir que um dos atributos da mensagem de tópico transmita a região da publicação das notícias.
Quando você recebe mensagens de uma assinatura com um filtro, não há taxas de mensagens 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.
Criar uma assinatura com filtro
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 Google Cloud, a Google Cloud CLI, as bibliotecas de cliente ou a API Pub/Sub.
Console
Para criar uma assinatura de pull com um filtro, siga estas etapas:
No Console do Google 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 Google 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
C++
Antes de tentar esse exemplo, siga as instruções de configuração do C++ em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C++.
C#
Antes de tentar esse exemplo, siga as instruções de configuração do C# em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub C#.
Go
Antes de tentar esse exemplo, siga as instruções de configuração do Go em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Go.
Java
Antes de tentar essa amostra, siga as instruções de configuração do Java em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Java.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
Node.js
Antes de tentar essa amostra, siga as instruções de configuração do Node.js em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Node.js.
PHP
Antes de tentar esse exemplo, siga as instruções de configuração do PHP em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub PHP.
Python
Antes de tentar esse exemplo, siga as instruções de configuração do Python em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Python.
Ruby
Antes de tentar esse exemplo, siga as instruções de configuração do Ruby em Guia de início rápido: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Pub/Sub Ruby.
O comprimento máximo de um filtro é 256 bytes. O filtro é uma propriedade imutável de uma assinatura. Depois de criar uma assinatura, não será possível atualizá-la para modificar o filtro.
Como os filtros afetam as métricas do backlog
Para monitorar a assinatura que você acabou de criar, consulte Monitorar assinaturas com filtros.
Se o filtro estiver ativado, as métricas de backlog incluirão apenas dados de mensagens que correspondam ao filtro. Esta é uma lista das métricas do backlog:
subscription/backlog_bytes
subscription/unacked_bytes_by_region
subscription/num_undelivered_messages
subscription/num_unacked_messages_by_region
subscription/oldest_unacked_message_age
subscription/oldest_unacked_message_age_by_region
topic/unacked_bytes_by_region
topic/num_unacked_messages_by_region
topic/oldest_unacked_messages_age_by_region
Para saber mais sobre essas métricas, consulte a lista de métricas do Pub/Sub.
Atualizar o filtro de uma assinatura
Não é possível atualizar o filtro de uma assinatura. Em vez disso, siga esta solução alternativa.
Faça um snapshot da assinatura em que você quer alterar o filtro.
Para saber mais sobre como criar um snapshot usando o console, consulte Criar um snapshot.
Crie uma nova assinatura com o novo filtro.
Para saber mais sobre como criar uma assinatura com um filtro, consulte Criar uma assinatura com um filtro.
No console do Google Cloud, acesse a página Assinaturas do Pub/Sub.
Clique na assinatura que você acabou de criar.
Na página de detalhes da assinatura, clique em Repetir mensagens.
Em Busca, clique em Para um snapshot.
Selecione o snapshot que você criou para a assinatura original na etapa 1 e clique em Busca.
Nenhuma mensagem será perdida durante a transição.
Mude os assinantes para usar a nova assinatura.
Depois de concluir este procedimento, é possível excluir a assinatura original.
Sintaxe para criar um filtro
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 name
:
Filtro | Descrição |
---|---|
attributes:name |
Mensagens com o atributo name |
NOT attributes:name |
Mensagens sem o atributo name |
attributes.name = "com" |
Mensagens com o atributo name e o valor de com |
attributes.name != "com" |
Mensagens sem o atributo name e o valor de com |
hasPrefix(attributes.name, "co") |
Mensagens com o atributo name e um valor que começa com co |
NOT hasPrefix(attributes.name, "co") |
Mensagens sem o atributo name e um valor que começa com co |
Operadores de comparação para a expressão de filtro
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.name = "com"
Inválido: o lado esquerdo do filtro é um valor.
"com" = attributes.name
Inválido: o filtro compara duas chaves
attributes.name = 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 para a expressão de filtro
É possível usar os operadores booleanos AND
, NOT
e OR
em um filtro. Os operadores
precisam estar em letras maiúsculas. Por exemplo, o
filtro a seguir é destinado a mensagens com o atributo iana.org/language_tag
,
mas sem o atributo name
e o valor de com
.
attributes:"iana.org/language_tag" AND NOT attributes.name = "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.name = "net" OR attributes.name = "org")
Inválido: operadores
AND
eOR
sem parêntesesattributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
Inválido: os operadores
AND
eOR
combinam expressões incompletas.attributes.name = "com" AND ("net" OR "org")
Você também pode usar o operador menos unário em vez do operador NOT
.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
Funções para a expressão de filtro
É possível usar a função hasPrefix
para filtrar atributos com valores que
começam com uma substring. hasPrefix
é a única função compatível com um filtro.
A correspondência de prefixo é aceita com a função hasPrefix
, mas as expressões regulares gerais não são aceitas.
hasPrefix(attributes.KEY, "SUBSTRING")
Substitua:
- KEY: o nome do atributo
- SUBSTRING: uma substring do valor