Lors de la création de votre système Pub/Sub, la désencapsulation de la charge utile peut aider vous vous connectez à d'autres systèmes qui ne répondent pas à toutes les exigences système un point de terminaison push Pub/Sub standard.
Voici quelques cas d'utilisation potentiels du déballage de la charge utile :
- Vous ne voulez pas écrire de code d'analyse de message spécifique à Pub/Sub pour vos points de terminaison HTTP push.
- Vous préférez recevoir les métadonnées des messages Pub/Sub en tant qu'en-têtes HTTP plutôt que dans le corps du message HTTP POST.
- Vous voulez envoyer des messages Pub/Sub et exclure les métadonnées Pub/Sub, par exemple lors de l'envoi de 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 Pub/Sub messages de toutes les métadonnées des messages, à l'exception de leurs données. En envoyant des données brutes données de message, les abonnés peuvent traiter le message sans avoir à se conformer les exigences système de Pub/Sub.
- Avec la désencapsulation de la charge utile, les données du message sont transmises directement .
- Sans désencapsulation de la charge utile, Pub/Sub fournit un objet JSON qui contient plusieurs champs de métadonnées de message et un champ de données de message. Dans ce le JSON doit être analysé pour récupérer les données du message, puis en base64. décodée.
Écrire des métadonnées
Après avoir activé la désencapsulation de la charge utile, vous pouvez utiliser l'option write metadata (écrire les métadonnées). ajoute les métadonnées de message précédemment supprimées dans l'en-tête de la requête.
- Écriture des métadonnées activée. Ajouter à nouveau les métadonnées du message à la requête en-tête. Fournit également les données brutes et décodées du message.
- Écriture de métadonnées 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 CLI Google Cloud et la propriété d'API NoWrapper
.
Par défaut, cette valeur est nulle.
Avant de commencer
- En savoir plus sur Pub/Sub abonnements et d'abonnements push. La désencapsulation de la charge utile ne peut être utilisée qu'avec des abonnements push.
- Découvrez comment configurer un abonnement push.
Exemple de messages encapsulés et désencapsulé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 fonction
fonctionnalité activée et publie un message sur mytopic
. Elle utilise une fonction de tri
avec la valeur some-key
et le type de média est déclaré comme suit :
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 une valeur encapsulée et une valeur non encapsulée. .
Message mis en forme
L'exemple suivant présente un message standard encapsulé Pub/Sub. Dans dans ce cas, la désencapsulation de la charge utile n'est pas activée.
Publier | Réception par le point de terminaison push |
---|---|
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 les métadonnées d'écriture désactivées
L'exemple suivant présente un message désencapsulé avec l'option d'écriture de métadonnées
est désactivé. Dans ce cas, les en-têtes x-goog-pubsub-*
et les attributs de message
ne sont pas incluses.
Publier | Réception par le point de terminaison push |
---|---|
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 en é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 de message sont inclus.
Publier | Réception par le point de terminaison push |
---|---|
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 la désencapsulation de la charge utile
Vous pouvez activer la distribution push de désencapsulation de la charge utile pour un abonnement à l'aide de la page Détails de l'abonnement de la console Google Cloud, de la Google Cloud CLI, ou les bibliothèques clientes.
Console
Dans la console Google 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 la section 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 des 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, procédez comme suit : 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 une désencapsulation de la charge utile incluant des
En-têtes HTTP, 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
: distribue les données du message directement en tant que corps HTTP.
Pour configurer un abonnement avec un déballage 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", écrit le Métadonnées du message Pub/Sub versx-goog-pubsub-<KEY>:<VAL>
de la requête HTTP. Écrire le message Pub/Sub aux 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
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.
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é la désencapsulation de la charge utile, Pub/Sub n'effectue pas
définir automatiquement un champ d'en-tête
de type de média dans votre requête. Si vous
ne définissez pas explicitement de champ d'en-tête Content-Type
, le serveur Web
le traitement de votre demande peut définir la valeur par défaut
application/octet-stream
ou interpréter la requête de manière inattendue.
Si vous avez besoin d'un en-tête Content-Type
, veillez à le déclarer explicitement
au moment de la publication pour chaque message publié. Pour ce faire, vous devez d'abord activer Écrire des métadonnées. Ce résultat de l'activation de l'écriture de métadonnées
comme indiqué dans les exemples fournis.
Étape suivante
- Si vous rencontrez des problèmes avec la désencapsulation de la charge utile, consultez Résoudre les problèmes de désencapsulation de la charge utile.