Ce document fournit des informations sur la publication de messages.
Une application d'éditeur crée et envoie des messages dans un sujet. Pub/Sub offre aux abonnés existants la distribution des messages au moins une fois et l'ordonnancement dans la mesure du possible.
Le flux général d'une application d'éditeur est organisé comme suit :
- Vous créez un message contenant vos données.
- Envoie une requête au serveur Pub/Sub pour publier le message dans le sujet spécifié.
Avant de commencer
Avant de configurer le workflow de publication, assurez-vous d'avoir effectué les tâches suivantes:
Rôles requis
Pour obtenir les autorisations nécessaires pour publier des messages dans un sujet, demandez à votre administrateur de vous attribuer le rôle IAM Éditeur Pub/Sub (roles/pubsub.publisher
) pour le sujet.
Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Vous devez disposer d'autorisations supplémentaires pour créer ou mettre à jour des sujets et des abonnements.
Format du message
Un message est constitué de champs contenant des données du message et des métadonnées. Spécifiez au moins l'un des éléments suivants dans le message :
- Les données du message
- Une clé de tri
- Attributs avec des métadonnées supplémentaires
Le service Pub/Sub ajoute les champs suivants au message :
- ID de message unique pour le sujet
- Horodatage correspondant au moment où le service Pub/Sub reçoit le message
Pour en savoir plus sur les messages, consultez Format des messages.
Publier des messages
Vous pouvez publier des messages à l'aide de la console Google Cloud, de Google Cloud CLI, de l'API Pub/Sub et des bibliothèques clientes. Les bibliothèques clientes peuvent publier des messages de manière asynchrone.
Les exemples suivants montrent comment publier un message dans un sujet.
Console
Pour publier un message, procédez comme suit :
Dans la console Google Cloud, accédez à la page Sujets Pub/Sub.
Cliquez sur l'ID du sujet.
Sur la page Détails du sujet, sous Messages, cliquez sur Publier un message.
Dans le champ Corps du message, saisissez les données associées au message.
Cliquez sur Publier.
gcloud
Pour publier un message, exécutez la commande gcloud pubsub topics publish :
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ [--attribute=KEY="VALUE",...]
Remplacez les éléments suivants :
- TOPIC_ID : ID du sujet
- MESSAGE_DATA : chaîne contenant les données du message
- KEY : clé d'un attribut de message
- VALUE : valeur de la clé de l'attribut de message
REST
Pour publier un message, envoyez une requête POST comme suit :
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)
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet avec le sujet
- TOPIC_ID : ID du sujet
Spécifiez les champs suivants dans le corps de la requête :
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", } ] }
Remplacez les éléments suivants :
- KEY : clé d'un attribut de message
- VALUE : valeur de la clé de l'attribut de message
- MESSAGE_DATA : chaîne encodée en base64 avec les données du message
Le message doit contenir un champ de données non vide ou au moins un attribut.
Si la requête aboutit, la réponse est un objet JSON avec l'ID du message. L'exemple suivant est une réponse avec un ID de message :
{ "messageIds": [ "19916711285", ] }
C++
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C++ qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C++.
C#
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C#.
Go
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Go qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
Java
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Java qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
PHP
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage PHP qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour PHP.
Python
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.
Ruby
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Ruby qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Après la publication d'un message, le service Pub/Sub renvoie l'ID du message à l'éditeur.
Utiliser des attributs pour publier un message
Vous pouvez intégrer des attributs personnalisés sous forme de métadonnées dans des messages Pub/Sub. Les attributs permettent de fournir des informations supplémentaires sur le message, comme sa priorité, son point de départ ou sa destination. Les attributs peuvent également être utilisés pour filtrer les messages au niveau de l'abonnement.
Suivez ces consignes pour utiliser des attributs dans vos messages:
Les attributs peuvent être des chaînes de texte ou des chaînes d'octets.
Vous ne pouvez pas définir plus de 100 attributs par message.
Les clés d'attribut ne doivent pas commencer par
goog
ni dépasser 256 octets.Les valeurs des attributs ne doivent pas dépasser 1 024 octets.
Le schéma du message peut être représenté comme suit :
{ "data": string, "attributes": { string: string, ... }, "messageId": string, "publishTime": string, "orderingKey": string }
Pour les doublons côté publication, il est possible de voir différentes valeurs publishTime
pour le même message d'origine côté client, même avec le même messageId
.
Le schéma JSON PubsubMessage
est publié dans la documentation REST et RPC. Vous pouvez utiliser des attributs personnalisés pour l'horodatage des événements.
Les exemples suivants montrent comment publier un message avec des attributs dans un sujet.
Console
Pour publier un message avec des attributs, procédez comme suit:
Dans la console Google Cloud, accédez à la page Sujets.
Cliquez sur le sujet pour lequel vous souhaitez publier des messages.
Sur la page des détails du sujet, cliquez sur Messages.
Cliquez sur Publier un message.
Dans le champ Corps du message, saisissez les données associées au message.
Sous Attributs du message, cliquez sur Ajouter un attribut.
Saisissez une paire clé-valeur.
Ajoutez d'autres attributs, si nécessaire.
Cliquez sur Publier.
gcloud
gcloud pubsub topics publish my-topic --message="hello" \ --attribute="origin=gcloud-sample,username=gcp,eventTime='2021-01-01T12:00:00Z'"
C++
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C++ qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C++.
C#
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C#.
Go
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Go qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
Java
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Java qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
Python
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.
Ruby
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Ruby qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Utiliser des clés de tri pour publier un message
Pour recevoir les messages dans l'ordre dans vos clients abonnés, vous devez configurer vos clients éditeurs de sorte qu'ils publient des messages avec des clés de tri.
Pour comprendre le concept de tri des clés, consultez la page Commander des messages.
Voici une liste des principales considérations relatives aux messages ordonnés pour les clients des éditeurs:
Commander dans un seul client d'éditeur: lorsqu'un seul client d'éditeur publie des messages avec la même clé de tri dans la même région, le client abonné reçoit ces messages dans l'ordre exact de publication. Par exemple, si un client éditeur publie les messages 1, 2 et 3 avec la clé de tri A, il les reçoit dans l'ordre 1, 2, 3.
Classement entre plusieurs clients éditeurs: l'ordre des messages reçus par les clients abonnés est cohérent dans l'ordre dans lequel ils ont été publiés dans la même région, même lorsque plusieurs clients éditeurs utilisent la même clé de tri. Toutefois, les clients de l'éditeur eux-mêmes ne connaissent pas cette commande.
Par exemple, si les clients éditeurs X et Y publient chacun des messages avec une clé de tri A, et que le message de X est reçu par Pub/Sub avant celui de Y, tous les clients abonnés reçoivent le message de X avant ceux de Y. Si un ordre de message strict est requis entre différents clients d'éditeurs, ces clients doivent mettre en œuvre un mécanisme de coordination supplémentaire pour s'assurer qu'ils ne publient pas simultanément des messages avec la même clé de tri. Par exemple, un service de verrouillage peut être utilisé pour conserver la propriété d'une clé de commande lors de la publication.
Tri dans plusieurs régions: le tri des messages n'est attendu que pour les messages publiés dans la même région. Par conséquent, assurez-vous que vos clients éditeurs utilisent les points de terminaison du service de localisation pour publier des messages dans la même région pour la même clé de tri. Les clients abonnés peuvent ensuite recevoir ces messages dans l'ordre.
Échecs de publication: en cas d'échec de la publication avec une clé de tri, les messages mis en file d'attente de la même clé de tri dans l'éditeur échouent, y compris les futures requêtes de publication de cette clé de tri. Vous devez reprendre la publication avec des clés de tri lorsque de tels échecs se produisent. Pour obtenir un exemple de reprise de l'opération de publication, consultez la section Relancer des requêtes avec des clés de tri.
Vous pouvez publier des messages avec des clés de tri à l'aide de la console Google Cloud, de Google Cloud CLI, de l'API Pub/Sub ou des bibliothèques clientes.
Console
Pour publier un message avec des attributs, procédez comme suit:
Dans la console Google Cloud, accédez à la page Sujets.
Cliquez sur le sujet pour lequel vous souhaitez publier des messages.
Sur la page des détails du sujet, cliquez sur Messages.
Cliquez sur Publier un message.
Dans le champ Corps du message, saisissez les données associées au message.
Dans le champ Tri des messages, saisissez une clé de tri.
Cliquez sur Publier.
gcloud
Pour publier un message avec une clé de tri, exécutez la commande gcloud pubsub topics publish
et l'option --ordering-key
:
gcloud pubsub topics publish TOPIC_ID \ --message=MESSAGE_DATA \ --ordering-key=ORDERING_KEY
Remplacez les éléments suivants :
- TOPIC_ID : ID du sujet
- MESSAGE_DATA : chaîne contenant les données du message
- ORDERING_KEY : chaîne avec une clé de tri
REST
Pour publier un message avec une clé de tri, envoyez une requête POST comme suit :
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)
Remplacez les éléments suivants :
- PROJECT_ID : ID du projet avec le sujet
- TOPIC_ID : ID du sujet
Spécifiez les champs suivants dans le corps de la requête :
{ "messages": [ { "attributes": { "KEY": "VALUE", ... }, "data": "MESSAGE_DATA", "ordering_key": "ORDERING_KEY", } ] }
Remplacez les éléments suivants :
- KEY : clé d'un attribut de message
- VALUE : valeur de la clé de l'attribut de message
- MESSAGE_DATA : chaîne encodée en base64 avec les données du message
- ORDERING_KEY : chaîne avec une clé de tri
Le message doit contenir un champ de données non vide ou au moins un attribut.
Si la requête aboutit, la réponse est un objet JSON avec l'ID du message. L'exemple suivant est une réponse avec un ID de message :
{ "messageIds": [ "19916711285", ] }
C++
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C++ qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C++.
C#
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage C# qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour C#.
Go
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Go qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
Java
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Java qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Java.
Node.js
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Node.js qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Node.js.
Python
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Python qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Python.
Ruby
Avant d'essayer cet exemple, suivez les instructions d'installation dans le langage Ruby qui se trouvent sur la page Démarrage rapide : utiliser des bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Ruby.
Surveiller un éditeur
Cloud Monitoring fournit un certain nombre de métriques permettant de surveiller les sujets.
Pour surveiller un sujet et maintenir un éditeur opérationnel, consultez la section Maintenir un éditeur opérationnel.
Étapes suivantes
Pour limiter les emplacements de stockage des données de message par Pub/Sub, consultez la page Restreindre les emplacements de ressources Pub/Sub.
Pour publier des messages avec un schéma, consultez Présentation du schéma.
Pour savoir comment configurer les options de distribution avancées, consultez les articles suivants: