Pembukaan payload untuk langganan push Pub/Sub

Saat mem-build sistem Pub/Sub, pembukaan payload dapat membantu Anda terhubung ke sistem lain yang tidak mematuhi semua persyaratan sistem penerapan endpoint push Pub/Sub standar.

Beberapa kasus penggunaan potensial untuk pembukaan payload adalah sebagai berikut:

  • Anda tidak ingin menulis kode penguraian pesan khusus Pub/Sub untuk endpoint push HTTP Anda.
  • Anda lebih memilih menerima metadata pesan Pub/Sub sebagai header HTTP, bukan metadata dalam isi HTTP POST.
  • Anda ingin mengirim pesan Pub/Sub dan mengecualikan metadata Pub/Sub, misalnya saat mengirim data ke API pihak ketiga.

Cara kerja pembukaan payload

Pembukaan payload adalah fitur yang menghapus pesan Pub/Sub dari semua metadata pesan, kecuali data pesan. Dengan mengirimkan data pesan mentah, pelanggan dapat memproses pesan tanpa harus mematuhi persyaratan sistem Pub/Sub.

  • Dengan pembukaan payload, data pesan akan dikirim langsung sebagai isi HTTP.
  • Tanpa pembukaan payload, Pub/Sub akan mengirimkan objek JSON yang berisi beberapa kolom metadata pesan dan satu kolom data pesan. Dalam hal ini, JSON harus diurai untuk mengambil data pesan, lalu didekode dengan base64.

Menulis metadata

Setelah mengaktifkan pembukaan payload, Anda dapat menggunakan opsi tulis metadata yang menambahkan metadata pesan yang sebelumnya telah dihapus ke header permintaan.

  • Menulis metadata diaktifkan. Tambahkan kembali metadata pesan ke header permintaan. Juga mengirimkan data pesan mentah yang telah didekode.
  • Tulis metadata dinonaktifkan. Hanya mengirimkan data pesan mentah yang telah didekode.

Metadata penulisan diekspos melalui Pub/Sub, argumen Google Cloud CLI --push-no-wrapper-write-metadata, dan properti API NoWrapper. Secara default, nilai ini adalah null.

Sebelum memulai

Contoh pesan yang digabungkan dan yang tidak digabungkan

Contoh berikut mengilustrasikan perbedaan antara mengirim pesan HTTP yang digabungkan dan tidak digabungkan. Dalam contoh ini, data pesan berisi string {"status": "Hello there"}.

Untuk contoh ini, langganan dibuat dengan fitur pembukaan payload yang diaktifkan dan memublikasikan pesan ke mytopic. Class ini menggunakan kunci urutan dengan nilai some-key dan jenis media dideklarasikan sebagai application/json.

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

Bagian berikut menunjukkan perbedaan antara pesan yang digabungkan dan tidak digabungkan.

Pesan yang dikemas

Contoh berikut menunjukkan pesan standar yang digabungkan untuk Pub/Sub. Dalam hal ini, payload pembukaan penggabungan tidak diaktifkan.

Memublikasikan Diterima Endpoint 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/..."
}

Pesan tidak digabungkan dengan metadata tulis dinonaktifkan

Contoh berikut menunjukkan pesan yang belum digabungkan dengan opsi tulis metadata dinonaktifkan. Dalam hal ini, header x-goog-pubsub-* dan atribut pesan tidak disertakan.

Memublikasikan Diterima Endpoint 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"}

Pesan yang tidak digabungkan dengan metadata tulis diaktifkan

Contoh berikut menunjukkan pesan yang belum digabungkan dengan opsi tulis metadata yang diaktifkan. Dalam hal ini, header x-goog-pubsub-* dan atribut pesan disertakan.

Memublikasikan Diterima Endpoint 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"}

Mengonfigurasi pembukaan payload

Anda dapat mengaktifkan pengiriman push unwrapping payload untuk langganan menggunakan halaman Subscription Details Konsol Google Cloud, Google Cloud CLI, atau Library Klien.

Konsol

  1. Di konsol Google Cloud, buka halaman Langganan.

    Buka langganan Pub/Sub

  2. Klik Buat langganan.

  3. Di kolom ID Langganan, masukkan nama.

    Untuk mengetahui informasi tentang cara memberi nama langganan, lihat Panduan memberi nama topik atau langganan.

  4. Pilih topik dari menu drop-down. Langganan ini menerima pesan dari topik.

  5. Untuk Jenis pengiriman, pilih Push.

  6. Untuk mengaktifkan pembukaan payload, pilih Enable payload unwrapping.

  7. (Opsional) Untuk mempertahankan metadata pesan di header permintaan, pilih Tulis metadata. Anda harus mengaktifkan opsi ini untuk menetapkan header Content-Type untuk pesan Anda.

  8. Tentukan URL endpoint.

  9. Pertahankan semua nilai default lainnya.

  10. Klik Create.

gcloud

Untuk mengonfigurasi langganan dengan pembukaan payload yang menyertakan header HTTP standar, jalankan perintah gcloud pubsub subscriptions create berikut:

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

Ganti kode berikut:

  • SUBSCRIPTION: nama atau ID langganan pull Anda.
  • TOPIC: ID topik.
  • PUSH_ENDPOINT: URL yang akan digunakan sebagai endpoint untuk langganan ini. Misalnya, https://myproject.appspot.com/myhandler
  • --push-no-wrapper: mengirimkan data pesan secara langsung sebagai isi HTTP.

Untuk mengonfigurasi langganan dengan pembukaan payload dan mengontrol penggunaan header x-goog-pubsub-*, jalankan perintah berikut:

gcloud pubsub subscriptions create SUBSCRIPTION \
  --topic TOPIC \
  --push-endpoint=PUSH_ENDPOINT \
  --push-no-wrapper \
  --push-no-wrapper-write-metadata
  • --push-no-wrapper-write-metadata: Jika true (benar), menulis metadata pesan Pub/Sub ke header x-goog-pubsub-<KEY>:<VAL> permintaan HTTP. Menulis atribut pesan Pub/Sub ke header <KEY>:<VAL> permintaan HTTP.

Python

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Python di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan Memulai: Menggunakan Library Klien. Untuk informasi selengkapnya, lihat dokumentasi referensi 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++

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di Panduan Memulai: Menggunakan Library Klien. Untuk informasi selengkapnya, lihat dokumentasi referensi 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan Memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan Memulai: Menggunakan Library Klien. Untuk informasi selengkapnya, lihat dokumentasi referensi 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

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan Memulai: Menggunakan Library Klien. Untuk informasi selengkapnya, lihat dokumentasi referensi 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.`);
}

Menetapkan header jenis konten dalam pesan

Setelah mengaktifkan pembukaan payload, Pub/Sub tidak otomatis menetapkan kolom header jenis media dalam permintaan Anda. Jika Anda tidak menetapkan kolom header Content-Type secara eksplisit, server web yang memproses permintaan Anda dapat menetapkan nilai default application/octet-stream atau menafsirkan permintaan dengan cara yang tidak diharapkan.

Jika Anda memerlukan header Content-Type, pastikan Anda mendeklarasikannya secara eksplisit pada waktu publikasi ke setiap pesan yang dipublikasikan. Untuk melakukannya, Anda harus mengaktifkan Tulis metadata terlebih dahulu. Hasil pengaktifan Metadata tulis ini ditampilkan dalam contoh yang diberikan.

Langkah selanjutnya