Entpacken der Nutzlast für Pub/Sub-Push-Abos

Beim Erstellen Ihres Pub/Sub-Systems kann das Entpacken der Nutzlast dazu beitragen, eine Verbindung zu anderen Systemen herzustellen, die nicht alle Systemanforderungen einer standardmäßigen Pub/Sub-Push-Endpunktimplementierung erfüllen.

Hier einige mögliche Anwendungsfälle für das Entfernen des Nutzlast-Wrappers:

  • Sie möchten keinen Pub/Sub-spezifischen Code zum Parsen von Nachrichten für Ihre HTTP-Push-Endpunkte schreiben.
  • Sie möchten Pub/Sub-Nachrichtenmetadaten lieber als HTTP-Header statt als Metadaten im HTTP-POST-Text erhalten.
  • Sie möchten Pub/Sub-Nachrichten senden und die Pub/Sub-Metadaten ausschließen, z. B. wenn Sie Daten an eine Drittanbieter-API senden.

Funktionsweise des Entpackens der Nutzlast

Das Entpacken der Nutzlast ist eine Funktion, mit der alle Metadaten aus Pub/Sub-Nachrichten entfernt werden, mit Ausnahme der Nachrichtendaten. Wenn Sie Rohnachrichtendaten senden, können Abonnenten die Nachricht verarbeiten, ohne die Systemanforderungen von Pub/Sub einhalten zu müssen.

  • Beim Entfernen des Nutzlast-Wrappers werden die Nachrichtendaten direkt als HTTP-Textkörper gesendet.
  • Ohne Entpacken der Nutzlast liefert Pub/Sub ein JSON-Objekt mit mehreren Nachrichtenmetadatenfeldern und einem Nachrichtendatenfeld. In diesem Fall muss das JSON-Objekt geparst werden, um die Nachrichtendaten abzurufen, und dann base64-decodiert werden.

Metadaten schreiben

Nachdem Sie das Entpacken der Nutzlast aktiviert haben, können Sie die Option Metadaten schreiben verwenden. Dadurch werden zuvor entfernte Nachrichtenmetadaten in den Anfrageheader eingefügt.

  • Metadaten schreiben muss aktiviert sein. Fügen Sie die Nachrichtenmetadaten wieder dem Anfrageheader hinzu. Sendet auch die decodierten Rohdaten der Nachricht.
  • Metadaten schreiben deaktiviert Sendet nur die decodierten Rohdaten der Nachricht.

Schreibmetadaten werden über Pub/Sub, das Google Cloud CLI-Argument --push-no-wrapper-write-metadata und die API-Eigenschaft NoWrapper bereitgestellt. Standardmäßig ist dieser Wert null.

Hinweise

Beispiel für gewickelte und ungewickelte Nachrichten

Die folgenden Beispiele veranschaulichen den Unterschied zwischen dem Senden einer verpackten und einer unverpackten HTTP-Nachricht. In diesen Beispielen enthalten die Nachrichtendaten den String {"status": "Hello there"}.

In diesem Beispiel wird ein Abo mit aktivierter Funktion zum Entfernen der Nutzlast erstellt und eine Nachricht an mytopic veröffentlicht. Es wird ein Sortierfeld mit dem Wert some-key verwendet und der Medientyp ist als application/json deklariert.

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

In den folgenden Abschnitten wird der Unterschied zwischen einer verpackten und einer entpackten Nachricht veranschaulicht.

Umgebrochene Nachricht

Das folgende Beispiel zeigt eine standardmäßige Pub/Sub-nachricht. In diesem Fall ist das Entfernen der Nutzlast nicht aktiviert.

Veröffentlichen Push-Endpunkt empfängt 
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/..."
}

Entpackte Nachricht mit deaktiviertem Schreiben von Metadaten

Das folgende Beispiel zeigt eine entpackte Nachricht, bei der die Option zum Schreiben von Metadaten deaktiviert ist. In diesem Fall sind die x-goog-pubsub-*-Header und die Nachrichtenattribute nicht enthalten.

Veröffentlichen Push-Endpunkt empfängt 
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"}

Entpackte Nachricht mit aktivierten Metadaten zum Schreiben

Das folgende Beispiel zeigt eine entpackte Nachricht, für die die Option zum Schreiben von Metadaten aktiviert ist. In diesem Fall sind die x-goog-pubsub-*-Header und die Nachrichtenattribute enthalten.

Veröffentlichen Push-Endpunkt empfängt 
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"}

Entpacken der Nutzlast konfigurieren

Sie können die Push-Zustellung mit Entfernen der Nutzlast für ein Abo auf der Seite Abodetails in der Google Cloud Console, über die Google Cloud CLI oder die Clientbibliotheken aktivieren.

Console

  1. Öffnen Sie in der Google Cloud Console die Seite Abos.

    Pub/Sub-Abos öffnen

  2. Klicken Sie auf Abo erstellen.

  3. Geben Sie im Feld Abo-ID einen Namen ein.

    Informationen zum Benennen eines Abos finden Sie unter Richtlinien für die Benennung eines Themas oder Abos.

  4. Wählen Sie im Drop-down-Menü ein Thema aus. Das Abo empfängt Nachrichten aus dem Thema.

  5. Wählen Sie als Zustellungstyp Push aus.

  6. Wenn Sie das Entpacken der Nutzlast aktivieren möchten, wählen Sie Entpacken der Nutzlast aktivieren aus.

  7. Optional: Wenn die Metadaten von Nachrichten im Anfrageheader beibehalten werden sollen, wählen Sie Metadaten schreiben aus. Sie müssen diese Option aktivieren, um einen Content-Type-Header für Ihre Nachrichten festzulegen.

  8. Geben Sie eine Endpunkt-URL an.

  9. Behalten Sie alle anderen Standardwerte bei.

  10. Klicken Sie auf Erstellen.

gcloud

Wenn du ein Abo mit Entfernen der Nutzlast mit Standard-HTTP-Headern konfigurieren möchtest, führe den folgenden gcloud pubsub subscriptions create-Befehl aus:

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

Ersetzen Sie Folgendes:

  • SUBSCRIPTION: der Name oder die ID Ihres Pull-Abos.
  • TOPIC: die ID des Themas.
  • PUSH_ENDPOINT: Die URL, die als Endpunkt für dieses Abo verwendet werden soll. z. B. https://myproject.appspot.com/myhandler.
  • --push-no-wrapper: Die Nachrichtendaten werden direkt als HTTP-Textkörper gesendet.

Führen Sie den folgenden Befehl aus, um ein Abo mit Entfernen der Nutzlast zu konfigurieren und die Verwendung von x-goog-pubsub-*-Headern zu steuern:

gcloud pubsub subscriptions create SUBSCRIPTION \
  --topic TOPIC \
  --push-endpoint=PUSH_ENDPOINT \
  --push-no-wrapper \
  --push-no-wrapper-write-metadata
  • --push-no-wrapper-write-metadata: Wenn „wahr“ ist, werden die Pub/Sub-Nachrichtenmetadaten in die x-goog-pubsub-<KEY>:<VAL>-Header der HTTP-Anfrage geschrieben. Schreibt die Pub/Sub-Nachrichtenattribute in die <KEY>:<VAL>-Header der HTTP-Anfrage.

Python

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Python in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Python API. 

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

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Java in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Java API. 

/*
 * 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++

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für C++ in der Kurzanleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zur Pub/Sub C++ API. 

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

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für Go in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Go API. 

import (
	"context"
	"fmt"
	"io"
	"time"

	"cloud.google.com/go/pubsub"
)

// createPushNoWrapperSubscription creates a push subscription where messages are delivered in the HTTP body.
func createPushNoWrapperSubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, endpoint string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// 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()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:       topic,
		AckDeadline: 10 * time.Second,
		PushConfig: pubsub.PushConfig{
			Endpoint: endpoint,
			Wrapper: &pubsub.NoWrapper{
				// Determines if message metadata is added to the HTTP headers of
				// the delivered message.
				WriteMetadata: true,
			},
		},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created push no wrapper subscription: %v\n", sub)
	return nil
}

Node.js

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Node.js API. 

/**
 * 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

Bevor Sie dieses Beispiel testen, folgen Sie der Einrichtungsanleitung für PHP in der Schnellstart-Anleitung: Clientbibliotheken verwenden. Weitere Informationen finden Sie in der Referenzdokumentation zu Pub/Sub Node.js API. 

/**
 * 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.`);
}

Content-Type-Header in der Nachricht festlegen

Nachdem du das Entfernen der Nutzlast aktiviert hast, setzt Pub/Sub in deiner Anfrage nicht automatisch ein Header-Feld für den Medientyp. Wenn Sie kein Content-Type-Header-Feld explizit festlegen, setzt der Webserver, der Ihre Anfrage verarbeitet, möglicherweise den Standardwert application/octet-stream oder interpretiert die Anfrage auf unerwartete Weise.

Wenn Sie einen Content-Type-Header benötigen, müssen Sie ihn bei der Veröffentlichung für jede einzelne veröffentlichte Nachricht explizit deklarieren. Dazu müssen Sie zuerst Metadaten schreiben aktivieren. Die Auswirkungen der Aktivierung von Metadaten schreiben sind in den vorgestellten Beispielen zu sehen.

Nächste Schritte