Topik yang dihentikan pengirimannya

Pelanggan mungkin tidak dapat menangani pesan karena berbagai alasan. Misalnya, mungkin ada masalah sementara saat mengambil data yang diperlukan untuk memproses pesan. Atau, pesan dapat berupa format yang tidak diharapkan oleh pelanggan.

Untuk mengelola pesan yang tidak terkirim yang tidak dapat dikonfirmasi oleh pelanggan, Pub/Sub dapat meneruskannya ke topik pesan yang dihentikan pengirimannya (juga dikenal sebagai antrean pesan yang dihentikan pengirimannya).

Sebelum memulai

  • Buat topik untuk konfigurasi topik yang dihentikan pengirimannya.

    Atau, jika Anda mengikuti semua petunjuk di halaman ini dari awal hingga akhir, Anda dapat membuat topik pada langkah berikutnya.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna mengelola topik dan langganan, minta administrator untuk memberi Anda peran IAM Pub/Sub Editor (roles/pubsub.editor) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Anda dapat mengonfigurasi kontrol akses di tingkat project dan di tingkat resource individual. Anda dapat membuat langganan dalam satu project dan melampirkannya ke topik yang berada dalam project lain. Pastikan Anda memiliki izin yang diperlukan untuk setiap project.

Cara kerja topik yang dihentikan pengirimannya

Jika aplikasi pelanggan tidak dapat mengonfirmasi pesan, Pub/Sub akan mencoba kembali pengiriman hingga batas waktu konfirmasi terpenuhi atau pesan berakhir. Setelah upaya pengiriman yang dikonfigurasi kira-kira berjumlah sekian kali, Pub/Sub dapat meneruskan pesan yang tidak dapat dikirim ke topik pesan yang tidak terkirim.

Saat meneruskan pesan yang tidak dapat dikirim, Pub/Sub akan membungkus pesan asli dalam pesan baru dan menambahkan atribut yang mengidentifikasi langganan sumber. Pesan kemudian dikirim ke topik pesan yang tidak terkirim yang ditentukan. Langganan terpisah yang dilampirkan ke topik pesan yang dihentikan pengirimannya kemudian dapat menerima pesan yang diteruskan ini untuk dianalisis dan di-debug secara offline.

Cara penghitungan upaya pengiriman maksimum

Pub/Sub hanya menghitung upaya pengiriman jika topik dead-letter dikonfigurasi dengan benar dan menyertakan izin IAM yang benar.

Jumlah maksimum upaya pengiriman diperkirakan karena Pub/Sub meneruskan pesan yang tidak dapat dikirimkan berdasarkan upaya terbaik. Layanan dapat meneruskan pesan setelah lebih sedikit upaya daripada yang dikonfigurasi, atau layanan dapat mencoba pengiriman beberapa kali lagi sebelum meneruskan.

Jumlah upaya pengiriman yang dilacak untuk pesan juga dapat direset ke nol, terutama untuk langganan pull dengan pelanggan yang tidak aktif. Akibatnya, pesan mungkin dikirim ke klien pelanggan lebih banyak daripada jumlah maksimum upaya pengiriman yang dikonfigurasi.

Properti topik dead-letter

Anda dapat menyetel properti langganan berikut pada topik pesan yang tidak terkirim.

  • Jumlah maksimum upaya pengiriman: Nilai numerik yang menandakan jumlah upaya pengiriman yang dilakukan Pub/Sub untuk pesan tertentu. Jika klien pelanggan tidak dapat mengonfirmasi pesan dalam jumlah percobaan pengiriman yang dikonfigurasi, pesan akan diteruskan ke topik pesan yang tidak terkirim.

    • Nilai default = 5
    • Nilai maksimum = 100
    • Nilai minimum = 5
  • Project dengan topik yang dihentikan pengirimannya: Jika topik yang dihentikan pengirimannya berada di project yang berbeda dengan langganan, Anda harus menentukan project dengan topik yang dihentikan pengirimannya. Tetapkan topik yang dihentikan pengirimannya ke topik yang berbeda dari topik yang terlampir langganannya.

Mengonfigurasi topik yang dihentikan pengirimannya

Langkah-langkah berikut menjelaskan alur kerja untuk menggunakan topik pesan yang tidak terkirim.

  1. Buat topik (untuk digunakan sebagai topik yang dihentikan pengirimannya).

  2. Buat langganan untuk topik yang dihentikan pengirimannya.

  3. Aktifkan Dead lettering di langganan Anda.

  4. Lampirkan topik yang Anda buat sebelumnya ke langganan Anda.

  5. Berikan peran yang diperlukan untuk menggunakan topik pesan yang tidak terkirim ke akun layanan Pub/Sub Anda.

Membuat topik untuk digunakan dengan topik yang dihentikan pengirimannya

Jika sudah membuat topik untuk digunakan dalam langganan, Anda dapat melewati langkah ini.

  1. Di konsol Google Cloud , buka halaman Topics.

    Buka Topik

  2. Klik Create topic.

  3. Masukkan Topic ID, misalnya, my-test-topic.

  4. Pertahankan opsi untuk langganan default, lalu klik Buat.

Menetapkan topik yang dihentikan pengirimannya pada langganan

Anda dapat menyetel topik pesan yang tidak terkirim pada langganan baru atau langganan yang sudah ada.

Menetapkan topik yang dihentikan pengirimannya pada langganan baru

Anda dapat membuat langganan dan menetapkan topik surat yang tidak terkirim menggunakan konsolGoogle Cloud , Google Cloud CLI, library klien, atau Pub/Sub API.

Konsol

Untuk membuat langganan dan menetapkan topik yang dihentikan pengirimannya, selesaikan langkah-langkah berikut:

  1. Di konsol Google Cloud , buka halaman Subscriptions.

    Buka Langganan

  2. Klik Buat langganan.

  3. Masukkan ID Langganan.

  4. Pilih topik yang ingin Anda gunakan dengan langganan Anda. Langganan menerima pesan dari topik. Ini bukan topik yang dihentikan pengirimannya. Anda akan memilihnya di langkah berikutnya.

  5. Di bagian Dead lettering, pilih Aktifkan dead lettering.

  6. Pilih topik pesan yang tidak terkirim dari menu drop-down.

    Jika topik surat yang tidak terkirim yang dipilih tidak memiliki langganan, sistem akan meminta Anda untuk membuatnya.

  7. Di kolom Upaya pengiriman maksimum, tentukan bilangan bulat antara 5 dan 100.

  8. Klik Create.

  9. Klik panel Detail untuk mengidentifikasi kemungkinan item tindakan. Jika ada item yang menampilkan ikon error , klik item tindakan untuk menyelesaikan masalah.

    Tab Dead Lettering dengan beberapa item tindakan.

gcloud

Untuk membuat langganan dan menetapkan topik yang dihentikan pengirimannya, gunakan perintah gcloud pubsub subscriptions create:

gcloud pubsub subscriptions create subscription-id \
  --topic=topic-id \
  --dead-letter-topic=dead-letter-topic-name \
  [--max-delivery-attempts=max-delivery-attempts] \
  [--dead-letter-topic-project=dead-letter-topic-project]

C++

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C++ di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API C++ Pub/Sub.

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& dead_letter_topic_id,
   int dead_letter_delivery_attempts) {
  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_dead_letter_policy()->set_dead_letter_topic(
      pubsub::Topic(project_id, dead_letter_topic_id).FullName());
  request.mutable_dead_letter_policy()->set_max_delivery_attempts(
      dead_letter_delivery_attempts);
  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";

  std::cout << "It will forward dead letter messages to: "
            << sub->dead_letter_policy().dead_letter_topic() << "\n";

  std::cout << "After " << sub->dead_letter_policy().max_delivery_attempts()
            << " delivery attempts.\n";
}

C#

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan C# di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API C# Pub/Sub.


using Google.Cloud.PubSub.V1;
using System;

public class CreateSubscriptionWithDeadLetterPolicySample
{
    public Subscription CreateSubscriptionWithDeadLetterPolicy(string projectId, string topicId, string subscriptionId, string deadLetterTopicId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        // This is the subscription you want to create with a dead letter policy.
        var subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        // This is an existing topic that you want to attach the subscription with dead letter policy to.
        var topicName = TopicName.FromProjectTopic(projectId, topicId);
        // This is an existing topic that the subscription with dead letter policy forwards dead letter messages to.
        var deadLetterTopic = TopicName.FromProjectTopic(projectId, deadLetterTopicId).ToString();
        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            DeadLetterPolicy = new DeadLetterPolicy
            {
                DeadLetterTopic = deadLetterTopic,
                // The maximum number of times that the service attempts to deliver a
                // message before forwarding it to the dead letter topic. Must be [5-100].
                MaxDeliveryAttempts = 10
            },
            AckDeadlineSeconds = 30
        };

        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        Console.WriteLine("Created subscription: " + subscription.SubscriptionName.SubscriptionId);
        Console.WriteLine($"It will forward dead letter messages to: {subscription.DeadLetterPolicy.DeadLetterTopic}");
        Console.WriteLine($"After {subscription.DeadLetterPolicy.MaxDeliveryAttempts} delivery attempts.");
        // Remember to attach a subscription to the dead letter topic because
        // messages published to a topic with no subscriptions are lost.
        return subscription;
    }
}

Go

Contoh berikut menggunakan versi utama library klien Go Pub/Sub (v2). Jika Anda masih menggunakan library v1, lihat panduan migrasi ke v2. Untuk melihat daftar contoh kode v1, lihat contoh kode yang tidak digunakan lagi.

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Go di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Go Pub/Sub.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createSubWithDeadLetter creates a subscription with a dead letter policy.
func createSubWithDeadLetter(w io.Writer, projectID, topic, subscription, fullyQualifiedDeadLetterTopic string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project-id/subscriptions/my-sub"
	// fullyQualifiedDeadLetterTopic := "projects/my-project-id/topics/my-dead-letter-topic"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	_, err = client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		DeadLetterPolicy: &pubsubpb.DeadLetterPolicy{
			DeadLetterTopic:     fullyQualifiedDeadLetterTopic,
			MaxDeliveryAttempts: 10,
		},
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription with dead letter topic: (%s)\n", fullyQualifiedDeadLetterTopic)
	fmt.Fprintln(w, "To process dead letter messages, remember to add a subscription to your dead letter topic.")
	return nil
}

Java

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Java di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi Java API Pub/Sub.

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.DeadLetterPolicy;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateSubscriptionWithDeadLetterPolicyExample {

  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    // This is the subscription you want to create with a dead letter policy.
    String subscriptionId = "your-subscription-id";
    // This is an existing topic that you want to attach the subscription with dead letter policy
    // to.
    String topicId = "your-topic-id";
    // This is an existing topic that the subscription with dead letter policy forwards dead letter
    // messages to.
    String deadLetterTopicId = "your-dead-letter-topic-id";

    CreateSubscriptionWithDeadLetterPolicyExample.createSubscriptionWithDeadLetterPolicyExample(
        projectId, subscriptionId, topicId, deadLetterTopicId);
  }

  public static void createSubscriptionWithDeadLetterPolicyExample(
      String projectId, String subscriptionId, String topicId, String deadLetterTopicId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);
      ProjectTopicName deadLetterTopicName = ProjectTopicName.of(projectId, deadLetterTopicId);

      DeadLetterPolicy deadLetterPolicy =
          DeadLetterPolicy.newBuilder()
              .setDeadLetterTopic(deadLetterTopicName.toString())
              // The maximum number of times that the service attempts to deliver a
              // message before forwarding it to the dead letter topic. Must be [5-100].
              .setMaxDeliveryAttempts(10)
              .build();

      Subscription request =
          Subscription.newBuilder()
              .setName(subscriptionName.toString())
              .setTopic(topicName.toString())
              .setDeadLetterPolicy(deadLetterPolicy)
              .build();

      Subscription subscription = subscriptionAdminClient.createSubscription(request);

      System.out.println("Created subscription: " + subscription.getName());
      System.out.println(
          "It will forward dead letter messages to: "
              + subscription.getDeadLetterPolicy().getDeadLetterTopic());
      System.out.println(
          "After "
              + subscription.getDeadLetterPolicy().getMaxDeliveryAttempts()
              + " delivery attempts.");
      // Remember to attach a subscription to the dead letter topic because
      // messages published to a topic with no subscriptions are lost.
    }
  }
}

Node.js

Sebelum mencoba contoh ini, ikuti petunjuk penyiapan Node.js di Panduan memulai: Menggunakan Library Klien. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Pub/Sub.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const deadLetterTopicNameOrId = 'YOUR_DEAD_LETTER_TOPIC_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 createSubscriptionWithDeadLetterPolicy(