Mengekspor pesan Pub/Sub Lite ke Pub/Sub

Catatan: Pub/Sub Lite tidak digunakan lagi. Mulai 18 Maret 2026, Pub/Sub Lite akan dinonaktifkan.

• Pelanggan saat ini: Pub/Sub Lite tetap berfungsi hingga 18 Maret 2026. Jika Anda belum menggunakan Pub/Sub Lite dalam periode 90 hari sebelum 24 September 2024 (26 Juni 2024 - 24 September 2024), Anda tidak akan dapat mengakses Pub/Sub Lite mulai 24 September 2024.
• Pelanggan baru: Pub/Sub Lite tidak lagi tersedia untuk pelanggan baru setelah 24 September 2024.

Anda dapat memigrasikan layanan Pub/Sub Lite ke Google Cloud Managed Service for Apache Kafka atau Pub/Sub.

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

Berikut adalah beberapa skenario saat Anda mungkin menggunakan fitur ini:

• Berinteraksi 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 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.

Topik Lite dapat memiliki kombinasi langganan ekspor dan langganan standar. Kedua jenis langganan tersebut 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 tepat satu topik Pub/Sub. Namun, topik Lite dapat memiliki beberapa langganan ekspor yang terhubung ke topik Pub/Sub yang berbeda (arsitektur fan-out). Anda juga dapat mengekspor dari beberapa topik Lite ke topik Pub/Sub yang sama (arsitektur fan-in).

Autentikasi

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

• pubsublite.subscriptions.create. Peran bawaan berikut berisi izin ini:

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

  Lihat Kontrol Akses untuk Pub/Sub Lite.

• pubsub.topics.get. Peran bawaan 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, aplikasi ini menggunakan agen layanan.

Setelah Anda membuat langganan ekspor pertama di project, agen layanan Pub/Sub Lite 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 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 topik individual. Sebaiknya berikan izin di tingkat topik, 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:[e-mail]
 --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 ekspor Lite harus berada di project dan lokasi yang sama dengan topik Lite yang dilampirkan. 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 Buat langganan Lite.

3. Masukkan ID langganan Lite.

4. Pilih topik Lite untuk menerima pesan.

5. Pilih Kirim pesan langsung 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. Centang kotak Enable dead lettering.
   2. Pilih topik Lite yang akan digunakan sebagai topik yang dihentikan pengirimannya, atau klik Buat Topik Lite untuk membuat topik yang dihentikan pengirimannya yang baru. Topik dead-letter 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 lain: projects/my-project-id/topics/my-topic-id.
• DEAD_LETTER_TOPIC_ID: Opsional. ID topik Lite yang akan digunakan sebagai topik surat mati. 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 berikut didukung:
  • active: Langganan mengekspor pesan Lite ke Pub/Sub. (Default.)
  • paused: Ekspor pesan Lite ditangguhkan.

Jika permintaan berhasil, command line akan menampilkan konfirmasi:

Created [SUBSCRIPTION_ID].

Protokol

Untuk membuat langganan ekspor Lite, 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 tempat menyimpan langganan Lite.
• PROJECT_NUMBER: Nomor project tempat 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 berikut didukung:
  • ACTIVE: Langganan mengekspor pesan Lite ke Pub/Sub.
  • PAUSED: Ekspor 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 menjadi tujuan ekspor. 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. Diperlukan 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, antara deliver-after-stored atau deliver-immediately.
• PUBSUB_TOPIC_NAME: Opsional. Nama topik Pub/Sub yang akan diekspor. Tentukan nama lengkap jika topik berada dalam project lain: 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 berikut didukung:
  • active: Langganan mengekspor pesan Lite ke Pub/Sub. (Default.)
  • paused: Ekspor 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 memperbarui 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: Region tempat langganan Lite dibuat.
• PROJECT_NUMBER: Nomor 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 berikut didukung:
  • ACTIVE: Langganan mengekspor pesan Lite ke Pub/Sub.
  • PAUSED: Ekspor 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: Ekspor 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 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.

Reservasi

Sebaiknya gunakan langganan ekspor dengan reservasi, bukan menetapkan secara eksplisit 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, pesan akan ditempatkan dalam topik surat mati, jika ada. Jika tidak ada topik dead-letter yang ditetapkan, pesan yang tidak kompatibel akan dihapus.

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

• Kunci. 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, dan ukuran kunci dan nilai maksimum per atribut.

Topik yang dihentikan pengirimannya

Untuk mempertahankan dan menangani pesan yang tidak kompatibel, sebaiknya gunakan topik pesan tidak terkirim. Anda dapat menetapkan topik dead-letter saat membuat langganan ekspor, atau Anda dapat memperbarui langganan ekspor yang ada untuk menggunakan topik dead-letter. 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. File ini harus berada di lokasi dan project yang sama dengan langganan ekspor, dan harus merupakan topik yang berbeda dari topik sumber.

Biasanya, topik yang dihentikan pengirimannya memiliki penggunaan throughput yang rendah. Oleh karena itu, sebaiknya tentukan reservasi ke topik yang dihentikan pengirimannya, bukan alokasikan 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 Anda menyelesaikan error, langganan ekspor akan otomatis dimulai ulang karena percobaan ulang berkala.

Harga

Anda akan ditagih untuk resource Pub/Sub Lite dan Pub/Sub yang digunakan langganan ekspor. Secara khusus, Anda akan ditagih untuk throughput dan penyimpanan langganan yang dialokasikan di langganan Pub/Sub Lite, yang dikonfigurasi untuk topik Pub/Sub Lite. Anda juga akan ditagih 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 langganan ekspor

Bagian ini menjelaskan beberapa tips pemecahan masalah untuk langganan ekspor.

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, error akan terjadi.

Untuk mendeteksi masalah ini:

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

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

Untuk mengatasi masalah ini, periksa topik Pub/Sub tujuan dan topik dead-letter (jika ada yang dikonfigurasi).

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

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

Pesan yang tidak kompatibel

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

Untuk mendeteksi masalah ini:

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

Untuk mengatasi masalah ini, gunakan topik dead-letter 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 aliran NO_CLIENT_TOKENS, yang menunjukkan bahwa batas per partisi byte atau pesan yang belum selesai telah tercapai. Hingga masalah teratasi, backlog akan meningkat untuk langganan ekspor terkait.

Error ini memiliki beberapa kemungkinan akar masalah. Sebagian besar kemungkinan penyebabnya terjadi di backend, tetapi periksa hal berikut:

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

Pengguna tidak diberi otorisasi untuk 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, Status saat ini 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 di project lain.
• Agen layanan 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 project. Error izin akan otomatis teratasi dalam waktu 10 menit.

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

Langkah selanjutnya

Pilih antara Pub/Sub atau Pub/Sub Lite.