Annullamento del wrapping del payload per le sottoscrizioni push Pub/Sub

Quando crei il tuo sistema Pub/Sub, l'annullamento del wrapping del payload può aiutarti a connetterti ad altri sistemi che non rispettano tutti i requisiti di sistema di un'implementazione standard dell'endpoint push Pub/Sub.

Di seguito sono riportati alcuni potenziali casi d'uso per l'annullamento del wrapping del payload:

  • Non vuoi scrivere codice di analisi dei messaggi specifico per Pub/Sub per i tuoi endpoint push HTTP.
  • Preferisci ricevere i metadati dei messaggi Pub/Sub come intestazioni HTTP anziché i metadati nel corpo della richiesta HTTP POST.
  • Vuoi inviare messaggi Pub/Sub ed escludere i metadati Pub/Sub, ad esempio quando invii dati a un'API di terze parti.

Come funziona l'annullamento del wrapping del payload

L'annullamento del wrapping del payload è una funzionalità che rimuove tutti i metadati dei messaggi Pub/Sub, ad eccezione dei dati dei messaggi. Inviando i dati dei messaggi non elaborati, i sottoscrittori possono elaborare il messaggio senza dover rispettare i requisiti di sistema di Pub/Sub.

  • Con l'annullamento del wrapping del payload, i dati dei messaggi vengono inviati direttamente come corpo della richiesta HTTP.
  • Senza l'annullamento del wrapping del payload, Pub/Sub invia un oggetto JSON che contiene più campi di metadati dei messaggi e un campo di dati dei messaggi. In questo caso, il JSON deve essere analizzato per recuperare i dati dei messaggi e poi decodificato in base64.

Scrivi metadati

Dopo aver abilitato l'annullamento del wrapping del payload, puoi utilizzare l'opzione Scrivi metadati che aggiunge i metadati dei messaggi rimossi in precedenza all'intestazione della richiesta.

  • Scrivi metadati abilitati. Aggiungi di nuovo i metadati dei messaggi all'intestazione della richiesta. Invia anche i dati dei messaggi non elaborati e decodificati.
  • Scrivi metadati disabilitati. Invia solo i dati dei messaggi non elaborati e decodificati.

La scrittura dei metadati è esposta tramite Pub/Sub, l'argomento --push-no-wrapper-write-metadata di Google Cloud CLI e la proprietà API NoWrapper. Per impostazione predefinita, questo valore è null.

Prima di iniziare

Esempio di messaggi con wrapping e senza wrapping

Gli esempi seguenti illustrano la differenza tra l'invio di un messaggio HTTP con wrapping e senza wrapping. In questi esempi, i dati dei messaggi contengono la stringa {"status": "Hello there"}.

Per questo esempio, viene creata una sottoscrizione con la funzionalità di annullamento del wrapping del payload abilitata e viene pubblicato un messaggio in mytopic. Utilizza una chiave di ordinamento con un valore di some-key e il tipo di supporto è dichiarato come application/json.

gcloud pubsub topics publish mytopic
   --message='{"status": "Hello there"}'
   --ordering-key="some-key"
   --attribute "Content-Type=application/json"

Le sezioni seguenti mostrano la differenza tra un messaggio con wrapping e senza wrapping.

Messaggio con wrapping

L'esempio seguente mostra un messaggio con wrapping Pub/Sub standard. In questo caso, l'annullamento del wrapping del payload non è abilitato.

Pubblica L'endpoint push riceve 
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/..."
}

Messaggio senza wrapping con scrittura dei metadati disabilitata

L'esempio seguente mostra un messaggio senza wrapping con l'opzione di scrittura dei metadati disabilitata. In questo caso, le intestazioni x-goog-pubsub-* e gli attributi dei messaggi non sono inclusi.

Pubblica L'endpoint push riceve 
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"}

Messaggio senza wrapping con scrittura dei metadati abilitata

L'esempio seguente mostra un messaggio senza wrapping con l'opzione di scrittura dei metadati abilitata. In questo caso, le intestazioni x-goog-pubsub-* e gli attributi dei messaggi sono inclusi.

Pubblica L'endpoint push riceve 
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"}

Configura l'annullamento del wrapping del payload

Puoi abilitare la distribuzione push dell'annullamento del wrapping del payload per una sottoscrizione utilizzando la pagina Dettagli sottoscrizione della console, Google Cloud CLI, o le librerie client. Google Cloud

Console

  1. Nella Google Cloud console, vai alla pagina Sottoscrizioni.

    Apri le sottoscrizioni Pub/Sub

  2. Fai clic su Crea sottoscrizione.

  3. Nel campo ID sottoscrizione, inserisci un nome.

    Per informazioni su come denominare una sottoscrizione, consulta le linee guida per la denominazione di un argomento o di una sottoscrizione.

  4. Seleziona un argomento dal menu a discesa. La sottoscrizione riceve i messaggi dall'argomento.

  5. In Tipo di consegna, seleziona Push.

  6. Per abilitare l'annullamento del wrapping del payload, seleziona Abilita l'annullamento del wrapping del payload.

  7. (Facoltativo) Per conservare i metadati dei messaggi nell'intestazione della richiesta, seleziona Scrivi metadati. Devi abilitare questa opzione per impostare un'intestazione Content-Type per i tuoi messaggi.

  8. Specifica un URL dell'endpoint.

  9. Mantieni tutti gli altri valori predefiniti.

  10. Fai clic su Crea.

gcloud

Per configurare una sottoscrizione con l'annullamento del wrapping del payload che include le intestazioni HTTP standard, esegui il seguente gcloud pubsub subscriptions create comando:

gcloud pubsub subscriptions create SUBSCRIPTION \
  --topic TOPIC \
  --push-endpoint=PUSH_ENDPOINT \
  --push-no-wrapper

Sostituisci quanto segue:

  • SUBSCRIPTION: il nome o l'ID della sottoscrizione pull.
  • TOPIC: l'ID dell'argomento.
  • PUSH_ENDPOINT: l'URL da utilizzare come endpoint per questa sottoscrizione. Ad esempio, https://myproject.appspot.com/myhandler
  • --push-no-wrapper: invia i dati dei messaggi direttamente come corpo della richiesta HTTP.

Per configurare una sottoscrizione con l'annullamento del wrapping del payload e controllare l'utilizzo delle intestazioni x-goog-pubsub-*, esegui il seguente comando:

gcloud pubsub subscriptions create SUBSCRIPTION \
  --topic TOPIC \
  --push-endpoint=PUSH_ENDPOINT \
  --push-no-wrapper \
  --push-no-wrapper-write-metadata
  • --push-no-wrapper-write-metadata: se è true, scrive i metadati dei messaggi Pub/Sub nelle intestazioni della richiesta HTTP.x-goog-pubsub-<KEY>:<VAL> Scrive gli attributi dei messaggi Pub/Sub nelle intestazioni <KEY>:<VAL> della richiesta HTTP.

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Java in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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++

Prima di provare questo esempio, segui le istruzioni di configurazione di C++ in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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'esempio seguente utilizza la versione principale della libreria client Go Pub/Sub (v2). Se utilizzi ancora la libreria v1, consulta la guida alla migrazione alla v2. Per visualizzare un elenco di esempi di codice della versione 1, consulta gli esempi di codice deprecati.

Prima di provare questo esempio, segui le istruzioni di configurazione di Go in Guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js in guida rapida all'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API Pub/Sub 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.`);
}

Imposta un'intestazione Content-Type nel messaggio

Dopo aver abilitato l'annullamento del wrapping del payload, Pub/Sub non imposta automaticamente un campo di intestazione del tipo di supporto nella richiesta. Se non imposti esplicitamente un campo di intestazione Content-Type, il server web che elabora la richiesta potrebbe impostare un valore predefinito di application/octet-stream o interpretare la richiesta in modo imprevisto.

Se hai bisogno di un'intestazione Content-Type, assicurati di dichiararla esplicitamente al momento della pubblicazione di ogni singolo messaggio pubblicato. Per farlo, devi prima abilitare Scrivi metadati. Il risultato dell'abilitazione di Scrivi metadati è mostrato negli esempi forniti.

Passaggi successivi