Filtrar mensajes

En esta página, se explica cómo crear suscripciones 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.

Cuando recibes mensajes de una suscripción con un filtro, no generas tarifas de salida para los mensajes que Pub/Sub confirma de forma automática. Se cobran tarifas por la entrega de mensajes y el almacenamiento relacionado con las búsquedas para estos mensajes.

Crea suscripciones con filtros

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 Cloud Console, la herramienta de línea de comandos de gcloud o la API de Pub/Sub.

Console

Para crear una suscripción de extracción con un filtro, sigue estos pasos:

  1. En Cloud Console, ve a la página Suscripciones.

    Ir a la página Suscripciones

  2. Haz clic en Crear suscripción.

  3. Ingresa el ID de suscripción.

  4. Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.

  5. En la sección Filtro de suscripción, ingresa la expresión de filtros.

  6. Haga clic en Crear.

Para crear una suscripción de envío con un filtro, sigue estos pasos:

  1. En Cloud Console, ve a la página Suscripciones.

    Ir a la página Suscripciones

  2. Haz clic en Crear suscripción.

  3. Ingresa el ID de suscripción.

  4. Elige o crea un tema desde el menú desplegable. La suscripción recibe mensajes del tema.

  5. En la sección Tipo de entrega, haz clic en Enviar.

  6. En el campo URL de extremo, ingresa la URL del extremo de envío.

  7. En la sección Filtro de suscripción, ingresa la expresión de filtros.

  8. 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.

La longitud máxima de un filtro es de 256 bytes. Después de crear la suscripción, no puedes modificar el filtro. Es posible que las métricas del trabajo pendiente incluyan mensajes que no coincidan con el filtro.

Filtra la sintaxis

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 domain:

Filtro Descripción
attributes:domain Mensajes con el atributo domain
NOT attributes:domain Mensajes sin el atributo domain
attributes.domain = "com" Mensajes con el atributo domain y con el valor de com
attributes.domain != "com" Mensajes sin el atributo domain y con el valor de com
hasPrefix(attributes.domain, "co") Mensajes con el atributo domain y con un valor que comienza con co
NOT hasPrefix(attributes.domain, "co") Mensajes sin el atributo domain y un valor que comienza con co

Operadores de comparación

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.domain = "com"
    
  • No válido: El lado izquierdo del filtro es un valor.

    "com" = attributes.domain
    
  • No válido: El filtro compara dos claves.

    attributes.domain = 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 el carácter dentro de un literal de string. 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

Puedes usar operadores booleanos en un filtro. Por ejemplo, el siguiente filtro es para mensajes con el atributo iana.org/language_tag, pero sin el atributo domain y el valor com.

attributes:"iana.org/language_tag" AND NOT attributes.domain = "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 y OR con paréntesis

    attributes:"iana.org/language_tag" AND (attributes.domain = "net" OR attributes.domain = "org")
    
  • No válido: Los operadores AND y OR sin paréntesis

    attributes:"iana.org/language_tag" AND attributes.domain = "net" OR attributes.domain = "org"
    
  • No válido: Los operadores AND y OR combinan expresiones incompletas

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

También puedes usar el operador menos en lugar del operador NOT.

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

Funciones

La función hasPrefix filtra los atributos con valores que comienzan con una substring.

hasPrefix(attributes.KEY, "SUBSTRING")

Reemplaza lo siguiente:

  • KEY: Es el nombre del atributo.
  • SUBSTRING: Es una substring del valor.