Désencapsulation de la charge utile pour les abonnements push Pub/Sub

Lorsque vous créez votre système Pub/Sub, la désencapsulation de la charge utile peut vous aider à vous connecter à d'autres systèmes qui ne respectent pas toutes les exigences de configuration système requise d'une implémentation de point de terminaison push Pub/Sub standard.

Voici quelques cas d'utilisation potentiels de la désencapsulation de la 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 de message Pub/Sub en tant qu'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 de message 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 la configuration système requise de Pub/Sub.

  • Avec la désencapsulation de la charge utile, les données de message sont distribuées directement en tant que corps HTTP.
  • Sans la désencapsulation de la charge utile, Pub/Sub distribue un objet JSON contenant plusieurs champs de métadonnées de message et un champ de données de message. Dans ce cas, le 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 des métadonnées qui ajoute les métadonnées de message précédemment supprimées à l'en-tête de requête.

  • Écrire des métadonnées activé Ajoutez les métadonnées de message à l'en-tête de requête. Cela permet également de distribuer les données de message brutes décodées.
  • Écrire des métadonnées désactivé Cela permet de n'envoyer que les données de message brutes décodées.

L'écriture de métadonnées est exposée via Pub/Sub, l'argument Google Cloud CLI --push-no-wrapper-write-metadata et la propriété d'API NoWrapper. Par défaut, cette valeur est nulle.

Avant de commencer

  • Découvrez les abonnements Pub/Sub et les abonnements push. 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ésencapsulation de la charge utile activée et publie un message sur mytopic. Il utilise une clé de commande avec la valeur some-key et le type de mé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 encapsulé Pub/Sub standard. Dans ce cas, la désencapsulation de la charge utile n'est pas activée.

Publier 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 non encapsulé avec l'écriture de métadonnées désactivée

L'exemple suivant montre un message non encapsulé avec l'option d'écriture de 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 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 non encapsulé avec l'écriture de métadonnées activée

L'exemple suivant montre un message non encapsulé avec l'option d'écriture de métadonnées activée. Dans ce cas, les x-goog-pubsub-* en-têtes et les attributs de message sont inclus.

Publier 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 la désencapsulation de la charge utile

Vous pouvez activer la distribution push de la désencapsulation de la charge utile pour un abonnement à l'aide de la page Détails de l'abonnement de la console, de Google Cloud CLI, ou des bibliothèques clientes. Google Cloud

Console

  1. Dans la Google Cloud console, accédez à la page Abonnements.

    Ouvrir les abonnements Pub/Sub

  2. Cliquez sur Créer un abonnement.

  3. 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.

  4. Sélectionnez un sujet dans le menu déroulant. L'abonnement reçoit les messages du sujet.

  5. Dans le champ Type de distribution, sélectionnez Push.

  6. Pour activer la désencapsulation de la charge utile, sélectionnez Activer la désencapsulation de la charge utile.

  7. (Facultatif) Pour conserver les métadonnées des messages dans l'en-tête de requête, sélectionnez Écrire des métadonnées. Vous devez activer cette option pour définir un en-tête Content-Type pour vos messages.

  8. Spécifiez une URL de point de terminaison.

  9. Conservez toutes les autres valeurs par défaut.

  10. 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 gcloud pubsub subscriptions create commande 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 push.
  • 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 désencapsulation 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 : lorsque la valeur est "true", écrit les métadonnées de message Pub/Sub dans les x-goog-pubsub-<KEY>:<VAL> en-têtes de la requête HTTP. Écrit les attributs de 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. 

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# endpoint = "https://my-test-project.appspot.com/push"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

no_wrapper = pubsub_v1.types.PushConfig.NoWrapper(write_metadata=True)
push_config = pubsub_v1.types.PushConfig(
    push_endpoint=endpoint, no_wrapper=no_wrapper
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "push_config": push_config,
        }
    )

print(f"Push no wrapper subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")
print(f"No wrapper configuration for subscription is: {no_wrapper}")

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 de l'API Pub/Sub pour Java . 

/*
 * Copyright 2016 Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package pubsub;


import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.PushConfig.NoWrapper;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreateUnwrappedPushSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      NoWrapper noWrapper =
          NoWrapper.newBuilder()
              // Determines if message metadata is added to the HTTP headers of
              // the delivered message.
              .setWriteMetadata(true)
              .build();
      PushConfig pushConfig =
          PushConfig.newBuilder().setPushEndpoint(pushEndpoint).setNoWrapper(noWrapper).build();

      // Create a push subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(subscriptionName, topicName, pushConfig, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

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 de l'API Pub/Sub pour C++ . 

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& endpoint) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_push_config()->set_push_endpoint(endpoint);
  request.mutable_push_config()->mutable_no_wrapper()->set_write_metadata(
      true);
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) throw std::move(sub).status();

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

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 afficher la liste des exemples de code v1, consultez les exemples de code obsolètes.

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 de l'API Pub/Sub pour Go.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createPushNoWrapperSubscription creates a push subscription where messages are delivered in the HTTP body.
func createPushNoWrapperSubscription(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()
	pbSubscription := &pubsubpb.Subscription{
		Name:               subscription,
		Topic:              topic,
		AckDeadlineSeconds: 10,
		PushConfig: &pubsubpb.PushConfig{
			PushEndpoint: endpoint,
			Wrapper: &pubsubpb.PushConfig_NoWrapper_{
				NoWrapper: &pubsubpb.PushConfig_NoWrapper{
					// Determines if message metadata is added to the HTTP headers of
					// the delivered message.
					WriteMetadata: true,
				},
			},
		},
	}
	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, pbSubscription)
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created push no wrapper subscription: %v\n", sub)
	return nil
}

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 de l'API Pub/Sub pour Node.js. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createPushSubscriptionNoWrapper(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId,
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
      // When true, writes the Pub/Sub message metadata to
      // `x-goog-pubsub-<KEY>:<VAL>` headers of the HTTP request. Writes the
      // Pub/Sub message attributes to `<KEY>:<VAL>` headers of the HTTP request.
      noWrapper: {
        writeMetadata: true,
      },
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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 de l'API Pub/Sub pour Node.js. 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createPushSubscriptionNoWrapper(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
      // When true, writes the Pub/Sub message metadata to
      // `x-goog-pubsub-<KEY>:<VAL>` headers of the HTTP request. Writes the
      // Pub/Sub message attributes to `<KEY>:<VAL>` headers of the HTTP request.
      noWrapper: {
        writeMetadata: true,
      },
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

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 ne définit pas automatiquement de 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 qui traite votre requête peut définir une 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, 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.

Étape suivante