Lorsque vous créez votre système Pub/Sub, le déballage de la charge utile peut vous aider à vous connecter à d'autres systèmes qui ne respectent pas toutes les exigences du système d'une implémentation de point de terminaison push Pub/Sub standard.
Voici quelques cas d'utilisation potentiels pour le déballage de charge utile :
- Vous ne souhaitez pas écrire de code d'analyse de message spécifique à Pub/Sub pour vos points de terminaison push HTTP.
- Vous préférez recevoir les métadonnées des messages Pub/Sub sous forme d'en-têtes HTTP plutôt que dans le corps HTTP POST.
- Vous souhaitez envoyer des messages Pub/Sub et exclure les métadonnées Pub/Sub, par exemple lorsque vous envoyez des données à une API tierce.
Fonctionnement de la désencapsulation de la charge utile
La désencapsulation de la charge utile est une fonctionnalité qui supprime toutes les métadonnées des messages Pub/Sub, à l'exception des données de message. En envoyant des données de message brutes, les abonnés peuvent traiter le message sans avoir à respecter les exigences système de Pub/Sub.
- Avec le déballage de la charge utile, les données du message sont fournies directement en tant que corps HTTP.
- Sans désencapsulation de la charge utile, Pub/Sub fournit un objet JSON contenant plusieurs champs de métadonnées de message et un champ de données de message. Dans ce cas, le fichier JSON doit être analysé pour récupérer les données du message, puis décodé en base64.
Écrire des métadonnées
Après avoir activé la désencapsulation de la charge utile, vous pouvez utiliser l'option Écrire les métadonnées, qui ajoute les métadonnées de message précédemment supprimées dans l'en-tête de requête.
- L'écriture des métadonnées est activée. Ajoutez de nouveau les métadonnées du message à l'en-tête de la requête. Cela permet également d'envoyer les données de message brutes décodées.
- L'écriture des métadonnées est désactivée. Cela permet de n'envoyer que les données de message brutes décodées.
Les métadonnées d'écriture sont exposées via Pub/Sub, l'argument --push-no-wrapper-write-metadata
de la Google Cloud CLI et la propriété d'API NoWrapper
.
Par défaut, cette valeur est nulle.
Avant de commencer
- En savoir plus sur les abonnements et les abonnements push Pub/Sub La désencapsulation de la charge utile ne peut être utilisée qu'avec les abonnements push.
- Découvrez comment configurer un abonnement push.
Exemple de messages encapsulés et non encapsulés
Les exemples suivants illustrent la différence entre l'envoi d'un message HTTP encapsulé et non encapsulé. Dans ces exemples, les données du message contiennent la chaîne {"status": "Hello there"}
.
Dans cet exemple, un abonnement est créé avec la fonctionnalité de décompression de la charge utile activée et publie un message sur mytopic
. Il utilise une clé de tri avec une valeur de some-key
et le type de contenu multimédia est déclaré comme application/json
.
gcloud pubsub topics publish mytopic --message='{"status": "Hello there"}' --ordering-key="some-key" --attribute "Content-Type=application/json"
Les sections suivantes montrent la différence entre un message encapsulé et un message non encapsulé.
Message encapsulé
L'exemple suivant montre un message Pub/Sub encapsulé standard. Dans ce cas, l'unwrapping de la charge utile n'est pas activé.
Publier | Le point de terminaison push reçoit |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 361 Content-Type: application/json User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com { "message": { "attributes": { "Content-Type": "application/json" }, "data": "eyJzdGF0dXMiOiAiSGVsbG8gdGhlcmUifQ==", // Base64 - {"status": "Hello there"} "messageId": "2070443601311540", "message_id": "2070443601311540", "publishTime": "2021-02-26T19:13:55.749Z", "publish_time": "2021-02-26T19:13:55.749Z" }, "subscription": "projects/myproject/..." } |
Message désencapsulé avec métadonnées d'écriture désactivées
L'exemple suivant montre un message non encapsulé avec l'option d'écriture des métadonnées désactivée. Dans ce cas, les en-têtes x-goog-pubsub-*
et les attributs de message ne sont pas inclus.
Publier | Le point de terminaison push reçoit |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
Content-Length: 25 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Message désencapsulé avec les métadonnées d'écriture activées
L'exemple suivant montre un message non encapsulé avec l'option d'écriture des métadonnées activée. Dans ce cas, les en-têtes x-goog-pubsub-*
et les attributs du message sont inclus.
Publier | Le point de terminaison push reçoit |
---|---|
data="{"status": "Hello there"}" ordering_key="some-key" attributes= { {"Content-Type", "application/json"} } |
x-goog-pubsub-subscription-name: "projects/myproject/..." x-goog-pubsub-message-id: "2070443601311540" x-goog-pubsub-publish-time: "2021-02-26T19:13:55.749Z" x-goog-pubsub-ordering-key: "some-key" Content-Type: application/json Content-Length: 12 User-Agent: CloudPubSub-Google Host: subscription-project.uc.r.appspot.com {"status": "Hello there"} |
Configurer l'unwrapping de la charge utile
Vous pouvez activer la diffusion push du déballage de charge utile pour un abonnement à l'aide de la page Détails de l'abonnement de la console Trusted Cloud , de Google Cloud CLI ou des bibliothèques clientes.
Console
Dans la console Trusted Cloud , accédez à la page Abonnements.
Cliquez sur Créer un abonnement.
Dans le champ ID d'abonnement, saisissez un nom.
Pour savoir comment nommer un abonnement, consultez Consignes de dénomination d'un sujet ou d'un abonnement.
Sélectionnez un thème dans le menu déroulant. L'abonnement reçoit les messages du sujet.
Dans le champ Type de distribution, sélectionnez Push.
Pour activer la désencapsulation de la charge utile, sélectionnez Activer la désencapsulation de la charge utile.
(Facultatif) Pour conserver les métadonnées des messages dans l'en-tête de requête, sélectionnez Écrire les métadonnées. Vous devez activer cette option pour définir un en-tête Content-Type pour vos messages.
Spécifiez une URL de point de terminaison.
Conservez toutes les autres valeurs par défaut.
Cliquez sur Créer.
gcloud
Pour configurer un abonnement avec désencapsulation de la charge utile qui inclut des en-têtes HTTP standards, exécutez la commande gcloud pubsub subscriptions create
suivante :
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper
Remplacez les éléments suivants :
SUBSCRIPTION
: nom ou ID de votre abonnement pull.TOPIC
: ID du sujet.PUSH_ENDPOINT
: URL à utiliser comme point de terminaison pour cet abonnement. Par exemple,https://myproject.appspot.com/myhandler
.--push-no-wrapper
: transmet les données du message directement en tant que corps HTTP.
Pour configurer un abonnement avec décompression de la charge utile et contrôler l'utilisation des en-têtes x-goog-pubsub-*
, exécutez la commande suivante :
gcloud pubsub subscriptions create SUBSCRIPTION \ --topic TOPIC \ --push-endpoint=PUSH_ENDPOINT \ --push-no-wrapper \ --push-no-wrapper-write-metadata
--push-no-wrapper-write-metadata
: si la valeur est "true", les métadonnées du message Pub/Sub sont écrites dans les en-têtesx-goog-pubsub-<KEY>:<VAL>
de la requête HTTP. Écrit les attributs du message Pub/Sub dans les en-têtes<KEY>:<VAL>
de la requête HTTP.
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.
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.
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
L'exemple suivant utilise la version majeure de la bibliothèque cliente Go Pub/Sub (v2). Si vous utilisez toujours la bibliothèque v1, consultez le guide de migration vers la v2. Pour consulter la liste des exemples de code de la version 1, consultez les exemples de code obsolètes.
Avant d'essayer cet exemple, suivez les instructions de configuration pour Go du guide de démarrage rapide : Utiliser les bibliothèques clientes. Pour en savoir plus, consultez la documentation de référence sur l'API Pub/Sub pour Go.
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.
Définir un en-tête de type de contenu dans votre message
Après avoir activé le déballage de charge utile, Pub/Sub ne définit pas automatiquement un champ d'en-tête de type de contenu dans votre requête. Si vous ne définissez pas explicitement un champ d'en-tête Content-Type
, le serveur Web qui traite votre requête peut définir une valeur par défaut de application/octet-stream
ou interpréter la requête de manière inattendue.
Si vous avez besoin d'un en-tête Content-Type
, assurez-vous de le déclarer explicitement au moment de la publication pour chaque message publié. Pour ce faire, vous devez d'abord activer l'option Écrire des métadonnées. Le résultat de l'activation de l'option Écrire des métadonnées est présenté dans les exemples fournis.
Étapes suivantes
- Si vous rencontrez des problèmes avec le déchiffrement de la charge utile, consultez Dépanner le déchiffrement de la charge utile.