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 de chaque message au moins une fois et l'ordonnancement des messages, 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.
- Envoyer une requête au serveur Pub/Sub pour publier le message au sujet spécifié.
Avant de commencer
Avant de configurer le workflow de publication, assurez-vous d'avoir effectué les opérations suivantes tâches:
- Découvrez les thèmes et le workflow de publication.
- Créez un sujet.
- Choisissez et créez un abonnement.
Rôles requis
Pour obtenir les autorisations dont vous avez besoin
pour publier des messages dans un sujet,
demandez à votre administrateur de vous accorder le
Éditeur Pub/Sub (roles/pubsub.publisher
) sur le sujet.
Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.
Vous avez besoin d'autorisations supplémentaires pour créer ou mettre à jour des sujets et des abonnements.
Format des messages
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 de message.
Publier des messages
Vous pouvez publier des messages avec la console Google Cloud, la Google Cloud CLI, l'API Pub/Sub, et les 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 l'élément suivant :
- 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 l'élément suivant :
- 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 l'élément suivant :
- 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 sont utilisés pour fournir des informations supplémentaires sur le message, telles que sa priorité, son origine ou sa destination. Les attributs peuvent également être utilisés pour filtrer les messages 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 avoir plus de 100 attributs par message.
Les clés d'attribut ne doivent pas commencer par
goog
et ne doivent pas dépasser 256 octets.Les valeurs d'attribut 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 le
REST et
RPC
dans la documentation Google Cloud. Vous pouvez utiliser des attributs personnalisés pour les codes temporels des événements.
Les exemples suivants montrent comment publier un message avec des attributs dans un sujet.
Console
Pour publier un message comportant des attributs, procédez comme suit:
Dans la console Google Cloud, accédez à la page Topics (Sujets).
Cliquez sur le sujet pour lequel vous souhaitez publier des messages.
Sur la page d'informations 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 de 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 publier des messages avec des clés de tri.
Pour comprendre le concept de clés d'ordonnancement, consultez Ordre des messages.
Voici une liste des points clés à prendre en compte concernant l'ordre de diffusion des messages destinés aux éditeurs clients:
Tri dans un seul client éditeur : lorsqu'un seul client é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 dans lequel ils ont été publiés. Par exemple, si un client éditeur publie les messages 1, 2 et 3 avec la clé de tri A, le client abonné les reçoit dans l'ordre 1, 2, 3.
Tri entre plusieurs clients éditeurs : l'ordre des messages reçus par les clients abonnés est cohérent avec 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 ne sont pas au courant de cette commande.
Par exemple, si les clients éditeurs X et Y publier des messages avec la clé de tri A, et le message de X est reçu par Pub/Sub avant les Y, puis tous les clients abonnés recevoir le message de X avant ceux de Y. Si un ordre strict des messages entre différents clients d'éditeurs est requis, ces clients doivent implémenter un mécanisme de coordination supplémentaire pour s'assurer qu'ils ne publient pas de messages avec la même clé de tri simultanément. Par exemple, un service de verrouillage peut servir à conserver la propriété d'une clé de commande lors de la publication.
Tri entre les régions : la garantie de diffusion ordonnée ne s'applique que lorsque les publications d'une clé d'ordonnancement se trouvent dans la même région. Si votre éditeur application publie des messages ayant la même clé de tri l'ordre ne peut pas être appliqué sur l'ensemble de ces publications. Les abonnés peuvent se connecter à n'importe quelle région et la garantie de commande est toujours maintenue.
Lorsque vous exécutez votre application dans Google Cloud, elle se connecte par défaut au point de terminaison Pub/Sub de la même région. Par conséquent, l'exécution de votre application dans une seule région Google Cloud garantit généralement que vous interagissez avec un seul dans la même région.
Lorsque vous exécutez votre application d'éditeur en dehors de Google Cloud ou dans plusieurs régions, vous pouvez vous assurer de vous connecter à une seule région à l'aide d'un point de terminaison géographique lorsque vous configurez votre client Pub/Sub. Tous les points de terminaison de l'emplacement pour Pub/Sub pointe vers des régions uniques. Pour en savoir plus sur des points de terminaison locaux, consultez Points de terminaison Pub/Sub Pour obtenir la liste de tous les points de terminaison localisés pour Pub/Sub, consultez la section Liste des points de terminaison localisés.
Échecs de publication: en cas d'échec de la publication avec une clé de tri, mise en file d'attente les messages associés à la même clé de tri chez l'éditeur échouent, y compris les futurs messages publier les requêtes de cette clé de tri. Vous devez reprendre la publication avec de l'ordre des clés lorsque de telles défaillances se produisent. Pour obtenir un exemple de reprise de l'opération de publication, consultez la section Réessayer les 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, la Google Cloud CLI, l'API Pub/Sub ou les bibliothèques clientes.
Console
Pour publier un message comportant 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 d'informations 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 l'élément suivant :
- 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 l'élément suivant :
- 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 l'élément suivant :
- 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 pour surveiller les sujets.
Pour surveiller un thème et s'assurer que les éditeurs sont opérationnels, consultez la page S'assurer que les éditeurs sont opérationnels.
Étape suivante
Pour limiter les emplacements de stockage des données de message par Pub/Sub, consultez Restreindre les emplacements des ressources Pub/Sub
Pour publier des messages à l'aide d'un schéma, consultez Présentation du schéma.
Pour savoir comment configurer des options de diffusion avancées, consultez les pages suivantes :