En este documento, se proporciona información sobre la publicación de mensajes.
Una aplicación de publicador crea y envía mensajes a un tema. Pub/Sub ofrece entrega de mensajes al menos una vez y orden de mejor esfuerzo a los suscriptores existentes.
El flujo general de una aplicación de publicador es el siguiente:
- Creación de un mensaje que contenga tus datos
- Envía una solicitud al servidor de Pub/Sub para publicar el mensaje en el tema especificado.
Antes de comenzar
Antes de configurar el flujo de trabajo de publicación, asegúrate de haber completado las siguientes tareas:
- Obtén más información sobre los temas y el flujo de trabajo de publicación.
- Crea un tema.
- Elige y crea una suscripción.
Funciones obligatorias
Si quieres obtener los permisos que necesitas para publicar mensajes en un tema, pídele a tu administrador que te otorgue el rol de IAM Publicador de Pub/Sub (roles/pubsub.publisher
) en el tema.
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.
Es posible que también puedas obtener los permisos necesarios a través de los roles personalizados o de otros roles predefinidos.
Necesitas permisos adicionales para crear o actualizar temas y suscripciones.
Formato del mensaje
Un mensaje consiste en campos con los datos y los metadatos del mensaje. Especifica al menos uno de los siguientes elementos en el mensaje:
- Los datos del mensaje
- Una clave de ordenamiento
- Atributos con metadatos adicionales
El servicio Pub/Sub agrega los siguientes campos al mensaje:
- Un ID de mensaje único para el tema
- Una marca de tiempo del momento en que el servicio de Pub/Sub recibe el mensaje
Para obtener más información sobre los mensajes, consulta Formato de los mensajes.
Publica mensajes
Puedes publicar mensajes con la consola de Google Cloud, Google Cloud CLI, la API de Pub/Sub y las bibliotecas cliente. Las bibliotecas cliente pueden publicar mensajes de manera asíncrona.
En los siguientes ejemplos, se muestra cómo publicar un mensaje en un tema.
Console
Para publicar un mensaje, sigue estos pasos:
En la consola de Google Cloud, ve a la página Temas de Pub/Sub.
Haz clic en el ID del tema.
En la página Detalles del tema en Mensajes, haz clic en Publicar mensaje.
En el campo Cuerpo del mensaje, ingresa los datos del mensaje.
Haz clic en Publish (Publicar).
gcloud
Para publicar un mensaje, usa el comando gcloud pubsub topics publish:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Reemplaza lo siguiente:
- TOPIC_ID: El ID del tema
- MESSAGE_DATA: Una string con los datos del mensaje
- KEY: La clave de un atributo de mensaje
- VALUE: El valor de la clave del atributo del mensaje
REST
Para publicar un mensaje, envía una solicitud POST como la siguiente:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Reemplaza lo siguiente:
- PROJECT_ID: El ID del proyecto con el tema
- TOPIC_ID: El ID del tema
Especifica los siguientes campos en el cuerpo de la solicitud:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Reemplaza lo siguiente:
- KEY: La clave de un atributo de mensaje
- VALUE: El valor de la clave del atributo del mensaje
- MESSAGE_DATA: Una string codificada en base64 con los datos del mensaje
El mensaje debe contener un campo de datos no vacío o al menos un atributo.
Si la solicitud se realiza correctamente, la respuesta es un objeto JSON con el ID de mensaje. El siguiente ejemplo es una respuesta con un ID de mensaje:
{ "messageIds": [ "19916711285", ] }
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.
Rita
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.
Después de que publicas un mensaje, el servicio de Pub/Sub le muestra el ID del mensaje al publicador.
Usa atributos para publicar un mensaje
Puedes incorporar atributos personalizados como metadatos en mensajes de Pub/Sub. Los atributos se usan para proporcionar información adicional sobre el mensaje, como su prioridad, origen o destino. Los atributos también se pueden usar para filtrar mensajes en la suscripción.
Sigue estos lineamientos para usar atributos en tus mensajes:
Los atributos pueden ser cadenas de texto o cadenas de bytes.
Puedes tener un máximo de 100 atributos por mensaje.
Las claves de atributo no deben comenzar con
goog
y no deben exceder los 256 bytes.Los valores del atributo no deben superar los 1,024 bytes.
El esquema del mensaje se puede representar de la siguiente manera:
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
En el caso de los duplicados del lado de la publicación, es posible ver diferentes valores de publishTime
para el mismo mensaje original del cliente, incluso con el mismo messageId
.
El esquema PubsubMessage
de JSON se publica como parte de la documentación de REST y RPC. Puedes usar atributos personalizados para las marcas de tiempo de eventos.
En los siguientes ejemplos, se muestra cómo publicar un mensaje con atributos en un tema.
Console
Para publicar un mensaje con atributos, sigue estos pasos:
En la consola de Google Cloud, ve a la página Temas.
Haz clic en el tema en el que deseas publicar mensajes.
En la página de detalles del tema, haz clic en Mensajes.
Haz clic en Publish message.
En el campo Cuerpo del mensaje, ingresa los datos del mensaje.
En Atributos del mensaje, haz clic en Agregar un atributo.
Ingresa un par clave-valor.
Si es necesario, agrega más atributos.
Haz clic en Publish (Publicar).
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
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.
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.
Rita
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.
Cómo usar claves de ordenamiento para publicar un mensaje
Si deseas recibir mensajes en orden en tus clientes suscriptores, debes configurar tus clientes publicadores para que publiquen mensajes con claves de ordenamiento.
Para comprender el concepto de claves de ordenamiento, consulta Mensajes de pedidos.
A continuación, se incluye una lista de consideraciones clave para los mensajes ordenados para clientes publicadores:
Realizar pedidos en un solo cliente publicador: Cuando un solo cliente publicador publica mensajes con la misma clave de ordenamiento en la misma región, el cliente suscriptor recibe esos mensajes en el orden exacto en el que se publicaron. Por ejemplo, si un cliente publicador publica los mensajes 1, 2 y 3 con la clave de ordenamiento A, el cliente suscriptor los recibe en el pedido 1, 2 y 3.
Realizar pedidos en varios clientes publicadores: El orden de los mensajes que reciben los clientes suscriptores es coherente con el orden en que se publicaron en la misma región, incluso cuando varios clientes publicadores usan la misma clave de ordenamiento. Sin embargo, los clientes publicadores no tienen conocimiento de este pedido.
Por ejemplo, si los clientes del publicador X e Y publican mensajes con la clave de orden A y Pub/Sub recibe el mensaje de X antes que el de Y, todos los clientes suscriptores reciben el mensaje de X antes que el de Y. Si se requiere un orden estricto de los mensajes entre diferentes clientes publicadores, esos clientes deben implementar un mecanismo de coordinación adicional para asegurarse de no publicar mensajes con la misma clave de ordenamiento de manera simultánea. Por ejemplo, se puede usar un servicio de bloqueo para mantener la propiedad de una clave de ordenamiento durante la publicación.
Pedidos entre regiones: El ordenamiento de los mensajes solo se espera para los mensajes publicados en la misma región. Por lo tanto, asegúrate de que tus clientes publicadores usen los extremos del servicio de ubicación para publicar mensajes en la misma región para la misma clave de ordenamiento. Luego, los clientes suscriptores pueden recibir estos mensajes en orden.
Fallas de publicación: Cuando falla la publicación con una clave de ordenamiento, fallan los mensajes en cola de la misma clave de ordenamiento del publicador, incluidas las solicitudes de publicación futuras de esta clave de ordenamiento. Deberás reanudar la publicación con claves de orden cuando se produzcan tales fallas. Para ver un ejemplo de cómo reanudar la operación de publicación, consulta Cómo reintentar las solicitudes con claves de ordenamiento.
Puedes publicar mensajes con claves de ordenamiento mediante la consola de Google Cloud, Google Cloud CLI, la API de Pub/Sub o las bibliotecas cliente.
Console
Para publicar un mensaje con atributos, sigue estos pasos:
En la consola de Google Cloud, ve a la página Temas.
Haz clic en el tema en el que deseas publicar mensajes.
En la página de detalles del tema, haz clic en Mensajes.
Haz clic en Publish message.
En el campo Cuerpo del mensaje, ingresa los datos del mensaje.
En el campo Ordenamiento de mensajes, ingresa una clave de ordenamiento.
Haz clic en Publish (Publicar).
gcloud
Para publicar un mensaje con una clave de ordenamiento, usa el comando gcloud pubsub topics publish
y la marca --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Reemplaza lo siguiente:
- TOPIC_ID: El ID del tema
- MESSAGE_DATA: Una string con los datos del mensaje
- ORDERING_KEY: Una string con clave de ordenamiento
REST
Para publicar un mensaje con una clave de ordenamiento, envía una solicitud POST como la siguiente:
POST https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID:publish Content-Type: application/json Authorization: Bearer $(gcloud auth application-default print-access-token)
Reemplaza lo siguiente:
- PROJECT_ID: El ID del proyecto con el tema
- TOPIC_ID: El ID del tema
Especifica los siguientes campos en el cuerpo de la solicitud:
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Reemplaza lo siguiente:
- KEY: La clave de un atributo de mensaje
- VALUE: El valor de la clave del atributo del mensaje
- MESSAGE_DATA: Una string codificada en base64 con los datos del mensaje
- ORDERING_KEY: Una string con clave de ordenamiento
El mensaje debe contener un campo de datos no vacío o al menos un atributo.
Si la solicitud se realiza correctamente, la respuesta es un objeto JSON con el ID de mensaje. El siguiente ejemplo es una respuesta con un ID de mensaje:
{ "messageIds": [ "19916711285", ] }
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.
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.
Rita
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.
Cómo supervisar a un publicador
Cloud Monitoring proporciona una serie de métricas para supervisar temas.
Para supervisar un tema y mantener un publicador en buen estado, consulta Mantén un publicador en buen estado.
¿Qué sigue?
Para restringir las ubicaciones en las que Pub/Sub almacena los datos de los mensajes, consulta Restringe las ubicaciones de recursos de Pub/Sub.
Para publicar mensajes con un esquema, consulta Descripción general del esquema.
Si quieres obtener información para configurar las opciones de entrega avanzadas, consulta los siguientes vínculos: