En esta página, se explica cómo crear suscripciones de Pub/Sub con filtros.
Cuando recibes mensajes de una suscripción con un filtro, solo recibes los mensajes que coinciden con el filtro. El servicio Pub/Sub confirma de forma automática los mensajes que no coinciden con el filtro. Puedes filtrar los mensajes según sus atributos, pero no según los datos que contienen.
Puedes tener varias suscripciones vinculadas a un tema, y cada una puede tener un filtro diferente.
Por ejemplo, si tienes un tema que recibe noticias de diferentes partes del mundo, puedes configurar una suscripción para filtrar las noticias que se publican solo desde una región específica. Para esta configuración, debes asegurarte de que uno de los atributos de los mensajes a temas que representa la región donde se publican las noticias.
Cuando recibes mensajes de una suscripción con un filtro, no incurres tarifas de mensajes salientes para los mensajes que Pub/Sub confirma la recepción de forma automática. Se cobran tarifas por la entrega de mensajes y el almacenamiento relacionado con las búsquedas para estos mensajes.
Crea una suscripción con un filtro
Las suscripciones de extracción y envío pueden tener filtros. Todos los suscriptores pueden recibir mensajes de suscripciones con filtros, incluidos los que usan la API de StreamingPull.
Puedes crear una suscripción con un filtro mediante la consola de Google Cloud, Google Cloud CLI, las bibliotecas cliente o la API de Pub/Sub.
Console
Para crear una suscripción de extracción con un filtro, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripciones.
Haz clic en Crear suscripción.
Ingresa el ID de suscripción.
Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
En la sección Filtro de suscripción, ingresa la expresión de filtros.
Haga clic en Crear.
Para crear una suscripción de envío con un filtro, sigue estos pasos:
En la consola de Google Cloud, ve a la página Suscripciones.
Haz clic en Crear suscripción.
Ingresa el ID de suscripción.
Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.
En la sección Tipo de entrega, haz clic en Enviar.
En el campo URL de extremo, ingresa la URL del extremo de envío.
En la sección Filtro de suscripción, ingresa la expresión de filtros.
Haga clic en Crear.
gcloud
Para crear una suscripción de extracción con un filtro, usa el comando gcloud pubsub subscriptions create
con la marca --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --message-filter='FILTER'
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Es el ID de la suscripción que se creará.
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
- FILTER: Es una expresión en la sintaxis de filtrado.
Para crear una suscripción de envío con un filtro, usa el comando gcloud pubsub subscriptions create
con las marcas --push-endpoint
y --message-filter
:
gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --push-endpoint=PUSH_ENDPOINT \ --message-filter='FILTER'
Reemplaza lo siguiente:
- SUBSCRIPTION_ID: Es el ID de la suscripción que se creará.
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
- PUSH_ENDPOINT: La URL del servidor en la que se ejecuta el suscriptor de envío
- FILTER: Es una expresión en la sintaxis de filtrado.
REST
Para crear una suscripción con un filtro, usa el método projects.subscriptions.create
.
PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID Authorization: Bearer $(gcloud auth print-access-token)
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto para crear la suscripción.
- SUBSCRIPTION_ID: Es el ID de la suscripción que se creará.
Para crear una suscripción de extracción con un filtro, especifica el filtro en el cuerpo de la solicitud:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "filter": "FILTER" }
Reemplaza lo siguiente:
- PROJECT_ID: el ID del proyecto con el tema
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
- FILTER: Es una expresión en la sintaxis de filtrado.
Para crear una suscripción de envío con un filtro, especifica el extremo de envío y el filtro en el cuerpo de la solicitud:
{ "topic": "projects/PROJECT_ID/topics/TOPIC_ID", "pushConfig": { "pushEndpoint": "PUSH_ENDPOINT" }, "filter": "FILTER" }
Reemplaza lo siguiente:
- PROJECT_ID: el ID del proyecto con el tema
- TOPIC_ID: Es el ID del tema para adjuntar a la suscripción.
- PUSH_ENDPOINT: La URL del servidor en la que se ejecuta el suscriptor de envío
- FILTER: Es una expresión en la sintaxis de filtrado.
C++
Antes de probar esta muestra, sigue las instrucciones de configuración de C++ en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C++.
C#
Antes de probar esta muestra, sigue las instrucciones de configuración de C# en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para C#.
Go
Antes de probar esta muestra, sigue las instrucciones de configuración de Go en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Go.
Java
Antes de probar esta muestra, sigue las instrucciones de configuración de Java en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Java.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración de Node.js en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Node.js.
PHP
Antes de probar esta muestra, sigue las instrucciones de configuración de PHP en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para PHP.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración de Python en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Python.
Ruby
Antes de probar esta muestra, sigue las instrucciones de configuración de Ruby en la guía de inicio rápido sobre el uso de bibliotecas cliente. Si quieres obtener más información, consulta la documentación de referencia de la API de Pub/Sub para Ruby.
La longitud máxima de un filtro es de 256 bytes. El filtro es es una propiedad inmutable de una suscripción. Después de crear una suscripción, no puedes actualizar la suscripción para modificar el filtro.
Cómo afectan los filtros a las métricas del backlog
Para supervisar la suscripción que acabas de crear, consulta Supervisa las suscripciones con filtros.
Si el filtrado está habilitado, las métricas de tareas pendientes solo incluyen los datos de los mensajes que coinciden con el filtro. La siguiente es una lista de las métricas de tareas pendientes:
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 obtener más información sobre estas métricas, consulta la lista de Métricas de Pub/Sub.
Actualiza el filtro de una suscripción
No puedes actualizar el filtro de una suscripción existente. En su lugar, sigue esta solución alternativa.
Crea una instantánea de la suscripción para la que deseas cambiar el filtro.
Para obtener más información sobre cómo tomar una instantánea con la consola, consulta Crea una instantánea.
Crea una nueva suscripción con el filtro nuevo.
Para obtener más información sobre cómo crear una suscripción con un filtro, consulta Cómo crear una suscripción con un filtro.
En la consola de Google Cloud, ve a la página de suscripciones a Pub/Sub.
Haz clic en la suscripción que acabas de crear.
En la página de detalles de la suscripción, haz clic en Repetir mensajes.
En Saltar, haz clic en A una instantánea.
Selecciona la instantánea que creaste para la suscripción original. en el paso 1 y, luego, en Buscar.
No perderás ningún mensaje durante la transición.
Cambia los suscriptores para que usen la suscripción nueva.
Después de completar este procedimiento, puedes borrar la suscripción original.
Sintaxis para crear un filtro
Para filtrar mensajes, escribe una expresión que funcione en atributos. Puedes escribir una expresión que coincida con la clave o con el valor de los atributos. El identificador attributes
selecciona los atributos del mensaje.
Por ejemplo, los filtros de la siguiente tabla seleccionan el atributo name
:
Filtro | Descripción |
---|---|
attributes:name |
Mensajes con el atributo name |
NOT attributes:name |
Mensajes sin el atributo name |
attributes.name = "com" |
Mensajes con el atributo name y con el valor de com |
attributes.name != "com" |
Mensajes sin el atributo name y con el valor de com |
hasPrefix(attributes.name, "co") |
Mensajes con el atributo name y con un valor que comienza con co |
NOT hasPrefix(attributes.name, "co") |
Mensajes sin el atributo name y un valor que comienza con co |
Operadores de comparación para la expresión de filtro
Puedes filtrar atributos con los siguientes operadores de comparación:
:
=
!=
El operador :
coincide con una clave en una lista de atributos.
attributes:KEY
Los operadores de igualdad coinciden con las claves y los valores. El valor debe ser un literal de string.
attributes.KEY = "VALUE"
Una expresión con un operador de igualdad debe comenzar con una clave, y el operador de igualdad debe comparar una clave y un valor.
Válido: El filtro compara una clave y un valor.
attributes.name = "com"
No válido: El lado izquierdo del filtro es un valor.
"com" = attributes.name
No válido: El filtro compara dos claves.
attributes.name = attributes.website
La clave y el valor distinguen entre mayúsculas y minúsculas, y deben coincidir exactamente con el atributo. Si una clave contiene caracteres distintos de guiones, guiones bajos o caracteres alfanuméricos, usa un literal de string.
attributes."iana.org/language_tag" = "en"
Para usar barras invertidas, comillas y caracteres no imprimibles en un filtro, escapa los caracteres dentro de un literal de cadena. También puedes usar secuencias de escape Unicode, hexadecimales y octales dentro de un literal de string.
Válido: Filtra los caracteres de escape dentro de un literal de string.
attributes:"\u307F\u3093\u306A"
No válido: Filtra los caracteres de escape sin un literal de string.
attributes:\u307F\u3093\u306A
Operadores booleanos para la expresión de filtro
Puedes usar los operadores booleanos AND
, NOT
y OR
en un filtro. Los operadores
debe estar en mayúsculas. Por ejemplo, el siguiente filtro es para mensajes con el atributo iana.org/language_tag
, pero sin el atributo name
y el valor com
.
attributes:"iana.org/language_tag" AND NOT attributes.name = "com"
El operador NOT
tiene la prioridad más alta. Para combinar los operadores AND
y OR
, usa paréntesis y expresiones completas.
Válido: operadores
AND
yOR
con paréntesisattributes:"iana.org/language_tag" AND (attributes.name = "net" OR attributes.name = "org")
No válido: Los operadores
AND
yOR
sin paréntesisattributes:"iana.org/language_tag" AND attributes.name = "net" OR attributes.name = "org"
No válido: Los operadores
AND
yOR
combinan expresiones incompletasattributes.name = "com" AND ("net" OR "org")
También puedes usar el operador menos en lugar del operador NOT
.
attributes.name = "com" AND -attributes:"iana.org/language_tag"
Funciones para la expresión de filtro
Puedes usar la función hasPrefix
para filtrar los atributos con valores que comienzan con una substring. hasPrefix
es la única función compatible en un filtro.
Si bien la concordancia de prefijos es compatible con la función hasPrefix
, no se admiten las expresiones regulares generales.
hasPrefix(attributes.KEY, "SUBSTRING")
Reemplaza lo siguiente:
- KEY: Es el nombre del atributo.
- SUBSTRING: Es una substring del valor.