Mengekspor pesan Pub/Sub Lite ke Pub/Sub

Dokumen ini menjelaskan cara menyiapkan ekspor otomatis pesan Pub/Sub Lite ke Pub/Sub.

Berikut adalah beberapa skenario yang dapat menggunakan fitur ini:

  • Lakukan interoperasi antara beban kerja yang menggunakan campuran Pub/Sub Lite dan Pub/Sub.
  • Memigrasikan beban kerja Pub/Sub Lite ke Pub/Sub.
  • Gunakan fitur Pub/Sub lanjutan, seperti langganan push dan pemfilteran, dari aplikasi yang ada yang didasarkan pada Pub/Sub Lite.
  • Menggabungkan beberapa pipeline data.

Ringkasan

Untuk mengekspor pesan dari Pub/Sub Lite ke Pub/Sub, Anda harus membuat jenis langganan khusus yang disebut langganan ekspor. Langganan ekspor menerima pesan dari topik Lite, mengonversinya menjadi pesan Pub/Sub, dan mengirim pesan yang dikonversi ke topik Pub/Sub tujuan.

Diagram ekspor pesan Pub/Sub Lite

Topik Lite dapat memiliki kombinasi antara langganan ekspor dan langganan standar. Kedua jenis langganan ini identik dalam hal penggunaan kuota dan throughput reservasi. Langganan ekspor menggunakan kapasitas throughput langganan Lite dan dikenai biaya untuk throughput publikasi Pub/Sub.

Langganan ekspor menghubungkan topik Lite ke satu topik Pub/Sub. Namun, topik Lite dapat memiliki beberapa langganan ekspor yang terhubung ke berbagai topik Pub/Sub (arsitektur fan-out). Anda juga dapat mengekspor dari beberapa topik Lite ke topik Pub/Sub yang sama (arsitektur fan-in).

Authentication

Langganan ekspor mengakses resource Pub/Sub Lite dan Pub/Sub. Untuk membuat langganan ekspor, Anda memerlukan izin berikut:

  • pubsublite.subscriptions.create. Peran yang telah ditetapkan berikut berisi izin ini:

    • roles/pubsublite.admin
    • roles/pubsublite.editor

    Lihat Kontrol Akses untuk Pub/Sub Lite.

  • pubsub.topics.get. Peran yang telah ditetapkan berikut berisi izin ini:

    • roles/pubsub.admin
    • roles/pubsub.editor
    • roles/pubsub.viewer

    Lihat Kontrol Akses untuk Pub/Sub.

Agen layanan

Langganan ekspor memublikasikan ke topik Pub/Sub atas nama Anda. Untuk melakukannya, metode ini menggunakan Akun Layanan yang dikelola Google.

Saat Anda membuat langganan ekspor pertama dalam sebuah project, agen layanan Pub/Sub Lite yang dikelola Google akan otomatis dibuat. Jika Anda membuat langganan ekspor tambahan dalam project yang sama, langganan tersebut akan menggunakan agen layanan yang sama. Agen layanan memiliki skema penamaan berikut: service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com.

Agen layanan dibuat dengan izin untuk memublikasikan ke semua topik Pub/Sub dan Pub/Sub Lite dalam project yang sama dengan langganan ekspor. Jika topik Pub/Sub tujuan Anda berada dalam project yang berbeda dengan langganan ekspor, Anda harus memberikan izin tambahan kepada agen layanan dengan menambahkan peran Pub/Sub Publisher (roles/pubsub.publisher). Anda dapat memberikan izin untuk seluruh project atau setiap topik. Sebaiknya berikan izin pada tingkat topik, dengan mengikuti prinsip hak istimewa terendah.

Untuk mengetahui informasi selengkapnya, lihat Mengontrol akses melalui Konsol Google Cloud. Anda juga dapat menggunakan perintah gcloud projects add-iam-policy-binding untuk menambahkan peran IAM:

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com
 --role=roles/pubsub.publisher

Ganti kode berikut:

  • TOPIC_NAME: Nama topik Pub/Sub tujuan untuk menambahkan binding kebijakan IAM.
  • PROJECT_NUMBER: Nomor project project langganan ekspor Pub/Sub Lite.

Membuat langganan ekspor

Anda dapat membuat langganan ekspor Lite dengan Konsol Google Cloud, Google Cloud CLI, atau Pub/Sub Lite API.

Langganan Lite Export harus berada dalam project dan lokasi yang sama dengan topik Lite yang terkait. Untuk membuat topik Lite, lihat Membuat dan mengelola topik Lite.

Jika Anda melampirkan langganan ekspor ke topik Lite, pastikan semua pesan yang dipublikasikan ke topik Lite kompatibel dengan Pub/Sub. Untuk mengetahui informasi selengkapnya, lihat Kompatibilitas pesan.

Setelah dibuat, Anda tidak dapat mengubah langganan ekspor menjadi langganan standar, atau sebaliknya.

Konsol

  1. Buka halaman Langganan Lite.

    Buka Langganan Lite

  2. Klik Create Lite subscription.

  3. Masukkan ID langganan Lite.

  4. Pilih topik Lite yang akan menerima pesan.

  5. Pilih Kirim pesan segera atau Kirim pesan setelah disimpan.

  6. Pilih jenis Offset awal.

  7. Pilih Ekspor ke topik Pub/Sub.

  8. Di daftar Destination topic, pilih topik Pub/Sub untuk menerima pesan Lite yang diekspor.

  9. Opsional. Tentukan topik yang dihentikan pengirimannya.

    1. Pilih kotak centang Aktifkan huruf yang dihentikan.
    2. Pilih topik Lite untuk digunakan sebagai topik yang dihentikan pengirimannya, atau klik Create Lite Topic untuk membuat topik baru yang dihentikan pengirimannya. Topik yang dihentikan pengirimannya harus berada di lokasi (zona atau region) dan project yang sama dengan langganan ekspor.

  10. Klik Create.

gcloud

Untuk membuat langganan ekspor, gunakan perintah gcloud pubsub lite-subscriptions create:

gcloud pubsub lite-subscriptions create SUBSCRIPTION_ID \
  --location=LOCATION \
  --topic=TOPIC_ID \
  --export-pubsub-topic=PUBSUB_TOPIC_NAME \
  --export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
  --export-desired-state=DESIRED_STATE

Ganti kode berikut:

  • SUBSCRIPTION_ID: ID langganan Lite yang akan dibuat.
  • LOCATION: Lokasi langganan Lite.
  • TOPIC_ID: ID topik Lite yang akan dilampirkan ke langganan Lite.
  • PUBSUB_TOPIC_NAME: Nama topik Pub/Sub yang akan diekspor. Tentukan nama lengkap jika topik berada dalam project yang berbeda: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: Opsional. ID topik Lite untuk digunakan sebagai topik yang dihentikan pengirimannya. Topik yang dihentikan pengirimannya harus berada di lokasi (zona atau region) dan project yang sama dengan langganan ekspor.
  • DESIRED_STATE: Opsional. Status awal langganan. Nilai-nilai berikut ini didukung:
    • active: Langganan mengekspor pesan Lite ke Pub/Sub. (Default.)
    • paused: Pengeksporan pesan Lite ditangguhkan.

Jika permintaan berhasil, command line akan menampilkan konfirmasi:

Created [SUBSCRIPTION_ID].

Protokol

Untuk membuat langganan Lite Export, kirim permintaan POST seperti berikut:

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

Ganti kode berikut:

  • REGION: Region untuk menyimpan langganan Lite.
  • PROJECT_NUMBER: Nomor project project untuk membuat langganan Lite.
  • LOCATION: Nama lokasi yang didukung Pub/Sub Lite.
  • SUBSCRIPTION_ID: ID langganan Lite.

Tentukan kolom berikut dalam isi permintaan:

{
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Ganti kode berikut:

  • DELIVERY_REQUIREMENT: Persyaratan pengiriman, DELIVER_AFTER_STORED atau DELIVER_IMMEDIATELY.
  • DESIRED_STATE: Status awal untuk langganan. Nilai-nilai berikut didukung:
    • ACTIVE: Langganan mengekspor pesan Lite ke Pub/Sub.
    • PAUSED: Pengeksporan pesan Lite ditangguhkan.
  • DEAD_LETTER_TOPIC_ID: ID topik Lite yang ada untuk digunakan sebagai topik yang dihentikan pengirimannya. Topik harus berada di lokasi (zona atau region) dan project yang sama dengan langganan ekspor itu sendiri.
  • PUBSUB_TOPIC_NAME: Nama topik Pub/Sub yang akan diekspor. Contoh format: projects/my-project-id/topics/my-topic-id.

Jika permintaan berhasil, responsnya adalah langganan Lite dalam format JSON:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      },
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
  "topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

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"

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

func createPubsubExportSubscription(w io.Writer, projectID, region, location, topicID, subID, pubsubTopicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// NOTE: location can be either a region ("us-central1") or a zone ("us-central1-a")
	// For a list of valid locations, see https://cloud.google.com/pubsub/lite/docs/locations.
	// location := "us-central1"
	// NOTE: topic and subscription must be in the same region/zone (e.g. "us-central1-a")
	// topicID := "my-topic"
	// subID := "my-subscription"
	// pubsubTopicID := "destination-topic-id"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %w", err)
	}
	defer client.Close()

	// Initialize the subscription to the oldest retained messages for each
	// partition.
	targetLocation := pubsublite.AtTargetLocation(pubsublite.Beginning)

	sub, err := client.CreateSubscription(ctx, pubsublite.SubscriptionConfig{
		Name:                fmt.Sprintf("projects/%s/locations/%s/subscriptions/%s", projectID, location, subID),
		Topic:               fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, location, topicID),
		DeliveryRequirement: pubsublite.DeliverImmediately, // Can also be DeliverAfterStored.
		// Configures an export subscription that writes messages to a Pub/Sub topic.
		ExportConfig: &pubsublite.ExportConfig{
			DesiredState: pubsublite.ExportActive, // Can also be ExportPaused.
			Destination: &pubsublite.PubSubDestinationConfig{
				Topic: fmt.Sprintf("projects/%s/topics/%s", projectID, pubsubTopicID),
			},
		},
	}, targetLocation)
	if err != nil {
		return fmt.Errorf("client.CreateSubscription got err: %w", err)
	}
	fmt.Fprintf(w, "Created export subscription: %s\n", sub.Name)
	return nil
}

Java

Sebelum menjalankan contoh ini, ikuti petunjuk penyiapan Java di Library Klien Pub/Sub Lite. 

import com.google.api.gax.rpc.AlreadyExistsException;
import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.BacklogLocation;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudRegionOrZone;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.SeekTarget;
import com.google.cloud.pubsublite.SubscriptionName;
import com.google.cloud.pubsublite.SubscriptionPath;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.ExportConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.PubSubConfig;
import com.google.cloud.pubsublite.proto.ExportConfig.State;
import com.google.cloud.pubsublite.proto.Subscription;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig;
import com.google.cloud.pubsublite.proto.Subscription.DeliveryConfig.DeliveryRequirement;
import java.util.concurrent.ExecutionException;

public class CreatePubsubExportSubscriptionExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String cloudRegion = "your-cloud-region";
    char zoneId = 'b';
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String pubsubTopicId = "destination-topic-id";
    long projectNumber = Long.parseLong("123456789");
    // True if using a regional location. False if using a zonal location.
    // https://cloud.google.com/pubsub/lite/docs/topics
    boolean regional = false;

    createPubsubExportSubscriptionExample(
        cloudRegion, zoneId, projectNumber, topicId, subscriptionId, pubsubTopicId, regional);
  }

  public static void createPubsubExportSubscriptionExample(
      String cloudRegion,
      char zoneId,
      long projectNumber,
      String topicId,
      String subscriptionId,
      String pubsubTopicId,
      boolean regional)
      throws Exception {

    CloudRegionOrZone location;
    if (regional) {
      location = CloudRegionOrZone.of(CloudRegion.of(cloudRegion));
    } else {
      location = CloudRegionOrZone.of(CloudZone.of(CloudRegion.of(cloudRegion), zoneId));
    }

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(location)
            .setName(TopicName.of(topicId))
            .build();

    SubscriptionPath subscriptionPath =
        SubscriptionPath.newBuilder()
            .setLocation(location)
            .setProject(ProjectNumber.of(projectNumber))
            .setName(SubscriptionName.of(subscriptionId))
            .build();

    com.google.pubsub.v1.TopicName pubsubTopicName =
        com.google.pubsub.v1.TopicName.of(String.valueOf(projectNumber), pubsubTopicId);

    Subscription subscription =
        Subscription.newBuilder()
            .setDeliveryConfig(
                // Possible values for DeliveryRequirement:
                // - `DELIVER_IMMEDIATELY`
                // - `DELIVER_AFTER_STORED`
                // You may choose whether to wait for a published message to be successfully written
                // to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
                // suitable for applications that need higher throughput.
                DeliveryConfig.newBuilder()
                    .setDeliveryRequirement(DeliveryRequirement.DELIVER_IMMEDIATELY))
            .setExportConfig(
                // Configures an export subscription that writes messages to a Pub/Sub topic.
                ExportConfig.newBuilder()
                    // Possible values for State:
                    // - `ACTIVE`: enable message processing.
                    // - `PAUSED`: suspend message processing.
                    .setDesiredState(State.ACTIVE)
                    .setPubsubConfig(
                        PubSubConfig.newBuilder().setTopic(pubsubTopicName.toString())))
            .setName(subscriptionPath.toString())
            .setTopic(topicPath.toString())
            .build();

    // Target location within the message backlog that the subscription should be initialized to.
    SeekTarget initialLocation = SeekTarget.of(BacklogLocation.BEGINNING);

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(location.extractRegion()).build();

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources, or
    // use "try-with-close" statement to do this automatically.
    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Subscription response = adminClient.createSubscription(subscription, initialLocation).get();
      System.out.println(response.getAllFields() + " created successfully.");
    } catch (ExecutionException e) {
      try {
        throw e.getCause();
      } catch (AlreadyExistsException alreadyExists) {
        System.out.println("This subscription already exists.");
      } catch (Throwable throwable) {
        throwable.printStackTrace();
      }
    }
  }
}

Python

Sebelum menjalankan contoh ini, ikuti petunjuk penyiapan Python di Library Klien Pub/Sub Lite. 

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsub_v1 import PublisherClient
from google.cloud.pubsublite import AdminClient, Subscription, ExportConfig
from google.cloud.pubsublite.types import (
    BacklogLocation,
    CloudRegion,
    CloudZone,
    SubscriptionPath,
    TopicPath,
)

def create_lite_pubsub_export_subscription(
    project_number,
    cloud_region="us-central1",
    zone_id="a",
    topic_id="my-topic-id",
    subscription_id="my-subscription-id",
    pubsub_topic_id="destination-topic-id",
    regional=True,
    target_location=BacklogLocation.BEGINNING,
):
    if regional:
        location = CloudRegion(cloud_region)
    else:
        location = CloudZone(CloudRegion(cloud_region), zone_id)

    topic_path = TopicPath(project_number, location, topic_id)
    subscription_path = SubscriptionPath(project_number, location, subscription_id)
    destination_topic_path = PublisherClient.topic_path(project_number, pubsub_topic_id)

    subscription = Subscription(
        name=str(subscription_path),
        topic=str(topic_path),
        delivery_config=Subscription.DeliveryConfig(
            # Possible values for delivery_requirement:
            # - `DELIVER_IMMEDIATELY`
            # - `DELIVER_AFTER_STORED`
            # You may choose whether to wait for a published message to be successfully written
            # to storage before the server delivers it to subscribers. `DELIVER_IMMEDIATELY` is
            # suitable for applications that need higher throughput.
            delivery_requirement=Subscription.DeliveryConfig.DeliveryRequirement.DELIVER_IMMEDIATELY,
        ),
        # Configures an export subscription that writes messages to a Pub/Sub topic.
        export_config=ExportConfig(
            # Possible values for desired_state:
            # - `ACTIVE`: enable message processing.
            # - `PAUSED`: suspend message processing.
            desired_state=ExportConfig.State.ACTIVE,
            pubsub_config=ExportConfig.PubSubConfig(
                topic=destination_topic_path,
            ),
        ),
    )

    # Initialize client that will be used to send requests across threads. This
    # client only needs to be created once, and can be reused for multiple requests.
    client = AdminClient(cloud_region)
    try:
        response = client.create_subscription(subscription, target_location)
        print(f"{response.name} created successfully.")
    except AlreadyExists:
        print(f"{subscription_path} already exists.")

Memperbarui langganan ekspor

Anda dapat memperbarui langganan Lite dengan Konsol Google Cloud, Google Cloud CLI, atau Pub/Sub Lite API. Perlu waktu hingga 30 detik untuk menerapkan setelan baru.

Konsol

  1. Buka halaman Langganan Lite.

    Buka Langganan Lite

  2. Klik ID langganan Lite.

  3. Di halaman Detail langganan Lite, klik Edit.

gCloud

Untuk memperbarui langganan Lite, gunakan perintah gcloud pubsub lite-subscriptions update:

gcloud pubsub lite-subscriptions update SUBSCRIPTION_ID \
--location=LOCATION \
--delivery-requirement=DELIVERY_REQUIREMENT \
--export-pubsub-topic=PUBSUB_TOPIC_NAME \
--export-dead-letter-topic=DEAD_LETTER_TOPIC_ID \
--export-desired-state=DESIRED_STATE

Ganti kode berikut:

  • SUBSCRIPTION_ID: ID langganan Lite
  • LOCATION: Lokasi langganan Lite.
  • DELIVERY_REQUIREMENT: Opsional. Persyaratan pengiriman, deliver-after-stored atau deliver-immediately.
  • PUBSUB_TOPIC_NAME: Opsional. Nama topik Pub/Sub yang menjadi tujuan ekspor. Tentukan nama lengkap jika topik berada dalam project berbeda: projects/my-project-id/topics/my-topic-id.
  • DEAD_LETTER_TOPIC_ID: ID topik Lite yang ada untuk digunakan sebagai topik yang dihentikan pengirimannya. Topik harus berada di lokasi (zona atau region) dan project yang sama dengan langganan ekspor itu sendiri.
  • DESIRED_STATE: Opsional. Status langganan yang diinginkan. Nilai-nilai berikut ini didukung:
    • active: Langganan mengekspor pesan Lite ke Pub/Sub. (Default.)
    • paused: Pengeksporan pesan Lite ditangguhkan.

Jika permintaan berhasil, command line akan menampilkan langganan Lite:

Updated subscription [SUBSCRIPTION_ID].
deliveryConfig:
deliveryRequirement: DELIVERY_REQUIREMENT
exportConfig:
currentState: DESIRED_STATE
deadLetterTopic: projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID
desiredState: DESIRED_STATE
pubsubConfig:
  topic: PUBSUB_TOPIC_NAME
name: projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
topic: projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID

Protokol

Untuk mengupdate langganan Lite, kirim permintaan PATCH seperti berikut:

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID?updateMask=deliveryConfig.deliveryRequirement,exportConfig
Authorization: Bearer $(gcloud auth print-access-token)

Ganti kode berikut:

  • REGION: Wilayah tempat langganan Lite dibuat.
  • PROJECT_NUMBER: Nomor project project tempat langganan Lite dibuat.
  • LOCATION: Lokasi tempat langganan Lite dibuat.
  • SUBSCRIPTION_ID: ID langganan Lite.

Tentukan kolom berikut dalam isi permintaan:

{
  "deliveryConfig": {
      "deliveryRequirement": "DELIVERY_REQUIREMENT",
  },
  "exportConfig": {
      "desiredState": "DESIRED_STATE",
      "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
      "pubsubConfig": {
          "topic": "PUBSUB_TOPIC_NAME"
      }
  }
}

Ganti kode berikut:

  • DELIVERY_REQUIREMENT: Persyaratan pengiriman, DELIVER_AFTER_STORED atau DELIVER_IMMEDIATELY.
  • DESIRED_STATE: Status yang diinginkan untuk langganan. Nilai-nilai berikut didukung:
    • ACTIVE: Langganan mengekspor pesan Lite ke Pub/Sub.
    • PAUSED: Pengeksporan pesan Lite ditangguhkan.
  • DEAD_LETTER_TOPIC_ID: ID topik Lite yang ada untuk digunakan sebagai topik yang dihentikan pengirimannya. Topik harus berada di lokasi (zona atau region) dan project yang sama dengan langganan ekspor itu sendiri.
  • PUBSUB_TOPIC_NAME: Nama topik Pub/Sub tujuan. Contoh format: projects/my-project-id/topics/my-topic-id.

Jika permintaan berhasil, responsnya adalah langganan Lite dalam format JSON:

{
"deliveryConfig": {
  "deliveryRequirement": "DELIVERY_REQUIREMENT",
},
"exportConfig": {
  "desiredState": "DESIRED_STATE",
  "deadLetterTopic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/DEAD_LETTER_TOPIC_ID",
  "pubsubConfig": { "topic": "PUBSUB_TOPIC_NAME" }
},
"name": "projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_NUMBER/locations/LOCATION/topics/TOPIC_ID",
}

Menjeda atau memulai langganan ekspor

Langganan ekspor memiliki setelan yang disebut status yang diinginkan, yang memiliki salah satu dari dua nilai:

  • Aktif: Langganan mengekspor pesan Lite ke Pub/Sub.
  • Dijeda: Pengeksporan pesan Lite ditangguhkan.

Untuk mengubah status yang diinginkan di Konsol Google Cloud:

  1. Buka halaman Langganan Lite.

    Buka Langganan Lite

  2. Klik ID langganan Lite.

  3. Di halaman Detail langganan Lite, klik Jeda atau Mulai.

Anda juga dapat memperbarui status yang diinginkan dengan menggunakan Google Cloud CLI atau Pub/Sub Lite API. Lihat Memperbarui langganan ekspor.

Praktik terbaik

Bagian ini menjelaskan beberapa praktik terbaik saat menggunakan langganan ekspor.

Pemesanan

Sebaiknya gunakan langganan ekspor dengan reservasi, bukan secara eksplisit menetapkan kapasitas throughput langganan.

Kompatibilitas pesan

Jika pesan Pub/Sub Lite tidak kompatibel dengan Pub/Sub, langganan ekspor tidak akan memublikasikan pesan ke Pub/Sub. Sebagai gantinya, sistem akan menempatkan pesan dalam topik yang dihentikan pengirimannya, jika ada yang ditetapkan. Jika tidak ada topik yang dihentikan pengirimannya yang ditetapkan, pesan yang tidak kompatibel akan dihapus.

Saat memublikasikan pesan ke topik Lite, perhatikan masalah kompatibilitas berikut:

  • Tombol. Kunci Pub/Sub Lite memiliki jenis bytes, sedangkan kunci pengurutan Pub/Sub adalah jenis string. Agar kompatibel, kunci Pub/Sub Lite hanya boleh berisi karakter UTF-8.

  • Atribut. Atribut pesan memiliki persyaratan berikut:

    • Agar kompatibel, semua atribut pesan Pub/Sub Lite harus memiliki satu nilai. Pub/Sub Lite mendukung atribut pesan dengan beberapa nilai, tetapi Pub/Sub hanya mendukung atribut nilai tunggal.
    • Atribut pesan tidak boleh melebihi batas pesan Pub/Sub, termasuk atribut maksimum per pesan, serta ukuran kunci dan nilai maksimum per atribut.

Topik yang dihentikan pengirimannya

Untuk mempertahankan dan menangani pesan yang tidak kompatibel, sebaiknya gunakan topik yang dihentikan pengirimannya. Anda dapat menetapkan topik yang dihentikan pengirimannya saat membuat langganan ekspor, atau Anda dapat memperbarui langganan ekspor yang sudah ada untuk menggunakan topik yang dihentikan pengirimannya. Jika menerima pesan yang tidak kompatibel dengan Pub/Sub, langganan akan memublikasikan pesan tersebut ke topik yang dihentikan pengirimannya.

Topik yang dihentikan pengirimannya adalah topik Pub/Sub Lite reguler. ID harus berada di lokasi dan project yang sama dengan langganan ekspor, dan harus berada di topik yang berbeda dari topik sumber.

Biasanya, topik yang dihentikan pengirimannya memiliki penggunaan throughput yang rendah. Oleh karena itu, sebaiknya tetapkan reservasi ke topik yang dihentikan pengirimannya, daripada mengalokasikan throughput ke topik.

Error pengiriman

Langganan ekspor mencoba mengirimkan semua pesan yang kompatibel ke topik Pub/Sub tujuan. Jika pengiriman pesan gagal, langganan ekspor akan ditangguhkan. Untuk menemukan kategori error, periksa metrik subscription/export_status. Nilai berikut menunjukkan error:

  • PERMISSION_DENIED: Izin tidak memadai untuk mengekspor pesan.
  • NOT_FOUND: Satu atau beberapa resource tidak ditemukan; misalnya, topik tujuan tidak ada.

Untuk mengetahui informasi selengkapnya tentang pemecahan masalah, lihat Memecahkan masalah langganan ekspor.

Setelah error teratasi, langganan ekspor otomatis dimulai ulang karena percobaan ulang berkala.

Harga

Anda dikenai biaya untuk resource Pub/Sub Lite dan Pub/Sub yang digunakan oleh langganan ekspor. Secara khusus, Anda akan dikenai biaya untuk throughput dan penyimpanan langganan yang dialokasikan di langganan Pub/Sub Lite, yang dikonfigurasi untuk topik Pub/Sub Lite. Anda juga dikenakan biaya untuk memublikasikan ke topik Pub/Sub tujuan. Lihat Harga Pub/Sub.

Tidak ada biaya tambahan untuk menggunakan fitur ekspor, dan tidak ada perbedaan harga antara langganan ekspor Pub/Sub Lite dan langganan standar.

Memecahkan masalah ekspor langganan

Bagian ini menjelaskan beberapa tips pemecahan masalah untuk mengekspor langganan.

Langganan ekspor dijeda

Jika langganan dijeda, tidak ada pesan yang diekspor.

Untuk mendeteksi masalah ini:

  • Konsol Google Cloud: Lihat detail langganan. Jika langganan dijeda, Status yang diinginkan dan Status saat ini adalah Paused.

  • Metrik: Metrik subscription/export_status adalah PAUSED.

Untuk mengatasi masalah ini, mulai langganan.

Topik tujuan atau topik yang dihentikan pengirimannya telah dihapus

Jika Anda menghapus topik Pub/Sub yang dilampirkan ke langganan ekspor, atau menghapus topik yang dihentikan pengirimannya, akan terjadi error.

Untuk mendeteksi masalah ini:

  • Konsol Google Cloud: Lihat detail langganan. Jika topik dihapus, Status saat ini adalah Not found.

  • Metrik: Metrik subscription/export_status. Jika topik dihapus, nilainya adalah NOT_FOUND.

Untuk mengatasi masalah ini, periksa topik Pub/Sub tujuan dan topik yang dihentikan pengirimannya (jika ada yang dikonfigurasi).

Jika Pub/Sub tujuan dihapus, buat ulang topik dengan nama yang sama. Langganan ekspor melanjutkan publikasi, dengan asumsi izin tidak berubah.

Jika topik yang dihentikan pengirimannya telah dihapus, buat topik yang dihentikan pengirimannya dan perbarui langganan ekspor untuk mereferensikannya.

Pesan yang tidak kompatibel

Jika pesan tidak kompatibel dengan Pub/Sub, pesan tersebut tidak akan diekspor.

Untuk mendeteksi masalah ini:

  • Metrik: Metrik subscription/unexportable_message_count menunjukkan jumlah pesan tidak kompatibel yang tidak dapat diekspor.

Untuk mengatasi masalah ini, gunakan topik yang dihentikan pengirimannya untuk mempertahankan pesan yang tidak kompatibel. Periksa pesan untuk menentukan penyebabnya, lalu ubah dan publikasikan ulang jika perlu. Lihat Kompatibilitas pesan.

Ekspor dibatasi

Untuk mendeteksi masalah ini:

  • Metrik: Metrik subscription/flow_control_status menunjukkan alasan kontrol alur dari NO_CLIENT_TOKENS, yang menunjukkan bahwa batas per partisi dari byte atau pesan yang belum terselesaikan telah tercapai. Hingga masalah ini diselesaikan, backlog akan meningkat untuk langganan ekspor terkait.

Error ini memiliki beberapa kemungkinan penyebab utama. Sebagian besar kemungkinan penyebabnya terjadi di backend, tetapi periksa hal-hal berikut:

  • Pastikan Anda memublikasikan pesan Lite yang berbagi kunci yang sama dengan kecepatan kurang dari 1 MiB/dtk per kunci. Langganan ekspor menulis kunci pesan Lite sebagai kunci pengurutan Pub/Sub, dan Pub/Sub memiliki batas 1 MiB/dtk pada setiap kunci pemesanan. Melebihi batas ini dapat menyebabkan throttling.

Pengguna tidak diizinkan melakukan tindakan ini

Agen layanan Pub/Sub Lite harus memiliki izin untuk memublikasikan ke topik Pub/Sub tujuan.

Untuk mendeteksi masalah ini:

  • Konsol Google Cloud: Lihat detail langganan. Jika ada error izin, Current state adalah Permission denied.

  • Metrik: Metrik subscription/export_status adalah PERMISSON_DENIED.

Misalnya, situasi berikut dapat menyebabkan error ini:

  • Agen layanan Pub/Sub Lite tidak memiliki izin atau peran yang benar untuk memublikasikan pesan ke topik Pub/Sub tujuan dalam project yang berbeda.
  • Agen layanan telah dihapus dari kebijakan IAM project induk langganan ekspor.
  • Agen layanan Pub/Sub Lite masih disiapkan. Agen layanan otomatis dibuat saat Anda membuat langganan ekspor pertama dalam sebuah project. Error izin akan otomatis diselesaikan dalam waktu 10 menit.

Untuk mengatasi masalah ini, periksa apakah agen layanan telah diberi izin atau peran yang benar. Lihat Agen layanan.

Langkah selanjutnya

Pilih antara Pub/Sub atau Pub/Sub Lite.