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 la entrega de mensajes al menos una vez y pedidos que se basan en el 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 al 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 el flujo de trabajo de publicación.
- Crea un tema.
- Elige y crea una suscripción.
Roles obligatorios
A fin de obtener los permisos que necesitas para publicar mensajes en un tema,
solicita a tu administrador que te otorgue el
Rol de IAM de 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 a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.
Necesitas permisos adicionales para crear o actualizar temas y suscripciones.
Formato de 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 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 forma asíncrona.
En los siguientes ejemplos, se demuestra 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 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.
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.
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
ni superar los 256 bytes.Los valores de los atributos no deben exceder 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 de 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 los eventos.
En los siguientes ejemplos, se muestra cómo publicar un mensaje con atributos a 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 para 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 de mensaje, haz clic en Agregar un atributo.
Ingresa un par clave-valor.
Agrega más atributos, si es necesario.
Haz clic en 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.
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.
Usa claves de ordenamiento para publicar un mensaje
Para recibir mensajes en orden en tus clientes suscriptor, debes configurar tus clientes publicador para que publiquen mensajes con claves de ordenamiento.
Para comprender el concepto de claves de orden, consulta Ordena mensajes.
Esta es una lista de consideraciones clave para los mensajes ordenados de los clientes del publicador:
Ordenamiento 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 orden 1, 2, 3.
Ordenar entre varios clientes publicadores: El orden de los mensajes recibidos por clientes suscriptores es coherente con el orden en que fueron publicados en la misma región, incluso si varios clientes editores usan la misma clave de ordenamiento. Sin embargo, los clientes del publicador no tienen conocimiento de este pedido.
Por ejemplo, si los clientes publicador X e Y publican mensajes con la clave de ordenamiento A, y Pub/Sub recibe el mensaje de X antes que el de Y, todos los clientes suscriptores recibirán el mensaje de X antes que el de Y. Si se requiere un orden de mensajes estricto en diferentes clientes del publicador, esos clientes deben implementar un mecanismo de coordinación adicional para asegurarse de no publicar mensajes con la misma clave de ordenamiento de forma simultánea. Por ejemplo, un servicio de bloqueo se puede usar para mantener la propiedad de una clave de ordenamiento durante una publicación.
Pedidos en diferentes regiones: Solo se aplica la garantía de entrega del pedido. cuando las publicaciones de una clave de pedido están en la misma región. Si tu aplicación del publicador publica mensajes con la misma clave de ordenamiento en diferentes regiones, no se puede aplicar el orden en esas publicaciones. Los suscriptores pueden conectarse a cualquier región y la garantía de pedidos se mantiene.
Cuando ejecutas tu aplicación en Google Cloud, esta se conecta de forma predeterminada al extremo de Pub/Sub en la misma región. Por lo tanto, ejecutar tu aplicación en una sola región dentro de Google Cloud suele garantizar que interactúes con una sola región.
Cuando ejecutas tu aplicación de publicador fuera de en Google Cloud o en varias regiones, puedes asegurarte conectarse a una sola región con un extremo de ubicación cuando configurar tu cliente de Pub/Sub. Todos los extremos de ubicación de Pub/Sub apunta a regiones únicas. Para obtener más información sobre los extremos de ubicación, consulta Extremos de Pub/Sub. Si quieres obtener una lista de todos los extremos de ubicación de Pub/Sub, consulta Lista de extremos de ubicación.
Errores de publicación: Cuando se produce un error de publicación con una clave de ordenamiento, los mensajes en cola de la misma clave de ordenamiento fallan en el publicador, incluidas las solicitudes de publicación futuras de esta clave de ordenamiento. Debes reanudar la publicación con y ordenar las claves cuando ocurren fallas. Para ver un ejemplo de cómo reanudar la operación de publicación, consulta Cómo reintentar solicitudes con claves de orden.
Puedes publicar mensajes con claves de ordenamiento con la consola de Google Cloud. como 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 para 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.
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.
Supervisa 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 Cómo restringir las ubicaciones de recursos de Pub/Sub.
Para publicar mensajes con un esquema, consulta Descripción general de los esquemas.
Para obtener información sobre cómo configurar las opciones de entrega avanzadas, consulta los siguientes vínculos: