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 al menos una entrega de mensajes y 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 los siguientes pasos: 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.
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.
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 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 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 atributos 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 de publicación, es posible ver diferentes valores de publishTime
para el mismo mensaje original del cliente, incluso con el mismo messageId
.
El esquema JSON PubsubMessage
se publica como parte del
REST y
RPC
en la documentación de Google Cloud. Puedes usar atributos personalizados para las marcas de tiempo de 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 suscriptores, debes configurar para que tus clientes publicadores publiquen mensajes con claves de ordenamiento.
Para comprender el concepto de ordenar claves, consulta Ordena mensajes.
Aquí hay una lista de consideraciones clave con respecto a los mensajes ordenados para el publicador clientes:
Realiza pedidos en un solo cliente publicador: Cuando un cliente publicador único publica mensajes con la misma clave de ordenamiento en la misma región el cliente suscriptor recibe esos mensajes en el orden exacto en 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 publicadores en sí no tienen conocimiento de este orden.
Por ejemplo, si los clientes publicadores X e Y publicar mensajes con la clave de ordenamiento A, y el mensaje de X es recibido por Pub/Sub antes que Y, luego, todos los clientes suscriptores recibir el mensaje de X antes del de Y. Si el orden de los mensajes es estricto entre diferentes publicadores, estos clientes deben implementar un de coordinación de anuncios para garantizar que no publiquen mensajes la misma clave de ordenamiento simultáneamente. Por ejemplo, un servicio de bloqueo se puede usar para mantener la propiedad de una clave de ordenamiento durante una publicación.
Ordenamiento entre regiones: El ordenamiento de mensajes solo se espera para los mensajes. publicados en la misma región. Por lo tanto, asegúrate de que tus clientes publicadores extremos de servicio de ubicación publicar mensajes en la misma región para el misma clave de ordenamiento. Los clientes suscriptores pueden recibir estos mensajes en en el orden personalizado.
Errores de publicación: Cuando se publica con una clave de ordenamiento, se produce un error y se pone en cola. los mensajes de la misma clave de ordenamiento en el publicador, lo que incluye Solicitudes de publicación 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 publicación, consulta Reintenta solicitudes con claves de ordenamiento.
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 Restringe las ubicaciones de recursos de Pub/Sub.
Para publicar mensajes con un esquema, consulta Descripción general del esquema.
Para obtener información sobre cómo configurar las opciones de entrega avanzadas, consulta los siguientes vínculos: