Pengiriman tepat satu kali

Halaman ini menjelaskan cara menerima dan mengonfirmasi pesan menggunakan fitur tepat satu kali Pub/Sub, yang memungkinkan Anda melacak dan mencegah pemrosesan pesan duplikat. Jika fitur diaktifkan, Pub/Sub menyediakan semantik berikut:

• Subscriber dapat menentukan apakah konfirmasi pesan berhasil.

• Tidak ada pengiriman ulang setelah pesan berhasil dikonfirmasi.

• Pengiriman ulang tidak terjadi saat pesan belum terkirim. Pesan dianggap belum selesai hingga batas waktu konfirmasi berakhir atau pesan dikonfirmasi.

• Jika ada beberapa pengiriman yang valid, karena masa berlaku batas waktu konfirmasi berakhir atau konfirmasi negatif yang dimulai klien, hanya ID konfirmasi terbaru yang dapat digunakan untuk mengonfirmasi pesan. Semua permintaan dengan ID konfirmasi sebelumnya akan gagal.

Dengan mengaktifkan pemrosesan tepat satu kali, pelanggan dapat memastikan pesan diproses satu kali dengan mengikuti pedoman berikut:

• Mengonfirmasi pesan dalam batas waktu konfirmasi.

• Mempertahankan informasi tentang progres pemrosesan pesan hingga pesan tersebut berhasil dikonfirmasi.

• Gunakan informasi tentang progres pemrosesan pesan untuk mencegah pekerjaan duplikat jika pengiriman konfirmasi gagal.

Hanya jenis langganan pull yang mendukung pengiriman tepat satu kali, termasuk pelanggan yang menggunakan StreamingPull API. Langganan push dan ekspor tidak mendukung pengiriman tepat satu kali.

Pub/Sub mendukung pengiriman tepat satu kali, dalam region cloud, berdasarkan ID pesan unik yang ditentukan Pub/Sub.

Versi library klien yang direkomendasikan

• Untuk performa terbaik, gunakan library klien versi terbaru, Python v2.13.6 atau yang lebih baru, Java v1.139.0 atau yang lebih baru, PHP v1.39.0 atau yang lebih baru, C# v3.2.0 atau yang lebih baru, C++ v2.1.0, Go v1.25.1 atau yang lebih baru, Node v3.2.0 atau yang lebih baru dan Ruby v2.12.1 atau yang lebih baru.

Pengiriman ulang versus duplikat

Penting untuk memahami perbedaan antara pengiriman ulang yang diharapkan dan tidak diharapkan.

• Pengiriman ulang dapat terjadi karena penolakan negatif yang dimulai klien terhadap pesan atau saat klien tidak memperpanjang batas waktu konfirmasi pesan sebelum batas waktu konfirmasi berakhir. Pengiriman ulang dianggap valid dan sistem berfungsi sebagaimana mestinya.

  Untuk memecahkan masalah pengiriman ulang, lihat Menangani duplikat.

• Duplikat terjadi saat pesan dikirim ulang setelah konfirmasi berhasil atau sebelum batas waktu konfirmasi berakhir.

• Pesan yang dikirim ulang mempertahankan ID pesan yang sama di antara upaya pengiriman ulang.

Langganan dengan pengiriman tepat satu kali yang diaktifkan tidak menerima pengiriman duplikat.

Dukungan pengiriman tepat satu kali di library klien

• Library klien yang didukung memiliki antarmuka untuk konfirmasi dengan respons (contoh: Go). Anda dapat menggunakan antarmuka ini untuk memeriksa apakah permintaan konfirmasi berhasil. Jika permintaan konfirmasi berhasil, klien dijamin tidak akan menerima pengiriman ulang. Jika permintaan konfirmasi gagal, klien dapat mengharapkan pengiriman ulang.

• Klien juga dapat menggunakan library klien yang didukung tanpa antarmuka konfirmasi. Namun, dalam kasus seperti itu, kegagalan konfirmasi dapat menyebabkan pengiriman ulang pesan secara diam-diam.

• Library klien yang didukung memiliki antarmuka untuk menyetel waktu perpanjangan sewa minimum (contoh: Go). Anda harus menetapkan nilai untuk perpanjangan masa sewa minimum ke angka yang tinggi untuk menghindari masa berlaku pengakuan terkait jaringan berakhir. Nilai maksimum ditetapkan pada 600 detik.

• Jika Anda menggunakan library klien Java dan menginisialisasi pelanggan dengan Channel gRPC kustom menggunakan metode setChannelProvider(), sebaiknya Anda juga menetapkan maxInboundMetadataSize ke setidaknya 1 MB saat membuat TransportChannelProvider. Untuk konfigurasi ini, Anda dapat menggunakan metode InstantiatingGrpcChannelProvider.Builder.setMaxInboundMetadataSize() atau ManagedChannelBuilder.maxInboundMetadataSize().

Nilai dan rentang default untuk variabel yang terkait dengan pengiriman tepat satu kali dan nama variabel mungkin berbeda di seluruh library klien. Misalnya, di library klien Java, variabel berikut mengontrol pengiriman tepat sekali.

Dalam kasus pengiriman tepat satu kali, permintaan modifyAckDeadline atau acknowledgment ke Pub/Sub gagal saat ID pengakuan sudah berakhir. Dalam kasus seperti itu, layanan menganggap ID konfirmasi yang sudah tidak berlaku sebagai tidak valid, karena pengiriman yang lebih baru mungkin sudah dalam proses. Hal ini sesuai dengan desain untuk pengiriman tepat satu kali. Kemudian, Anda akan melihat permintaan acknowledgment dan ModifyAckDeadline menampilkan respons INVALID_ARGUMENT. Jika pengiriman tepat satu kali dinonaktifkan, permintaan ini akan menampilkan OK jika ID konfirmasi telah habis masa berlakunya.

Untuk memastikan bahwa permintaan acknowledgment dan ModifyAckDeadline memiliki ID konfirmasi yang valid, pertimbangkan untuk menetapkan nilai minDurationPerAckExtension ke angka yang tinggi.

Pertimbangan regional

Jaminan pengiriman tepat satu kali hanya berlaku saat pelanggan terhubung ke layanan di region yang sama. Jika aplikasi pelanggan Anda tersebar di beberapa wilayah, hal ini dapat menyebabkan pengiriman pesan duplikat, meskipun pengiriman tepat satu kali diaktifkan. Penerbit dapat mengirim pesan ke wilayah mana pun dan jaminan pengiriman tepat satu kali tetap dipertahankan.

Saat Anda menjalankan aplikasi dalam Trusted Cloud, secara default aplikasi tersebut terhubung ke endpoint Pub/Sub di region yang sama. Oleh karena itu, menjalankan aplikasi Anda di satu region dalam Trusted Cloud biasanya memastikan Anda berinteraksi dengan satu region.

Saat menjalankan aplikasi pelanggan di luar Trusted Cloud atau di beberapa region, Anda dapat menjamin bahwa Anda terhubung ke satu region dengan menggunakan endpoint lokasi saat mengonfigurasi klien Pub/Sub. Semua endpoint lokasi untuk Pub/Sub mengarah ke satu region. Untuk mempelajari lebih lanjut endpoint lokasi, lihat Endpoint Pub/Sub. Untuk mengetahui daftar semua endpoint berbasis lokasi untuk Pub/Sub, lihat Daftar endpoint berbasis lokasi.

Membuat langganan dengan pengiriman tepat satu kali

Anda dapat membuat langganan dengan pengiriman persis sekali menggunakan Trusted Cloud konsol, Google Cloud CLI, library klien, atau Pub/Sub API.

Langganan pull

gcloud pubsub subscriptions create SUBSCRIPTION_ID \
  --topic=TOPIC_ID \
  --enable-exactly-once-delivery

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

{
  "topic": "projects/PROJECT_ID/topics/TOPIC_ID",
  "enableExactlyOnceDelivery": true,
}

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) {
  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.set_enable_exactly_once_delivery(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";
}

using Google.Cloud.PubSub.V1;
using Grpc.Core;

public class CreateSubscriptionWithExactlyOnceDeliverySample
{
    public Subscription CreateSubscriptionWithExactlyOnceDelivery(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            EnableExactlyOnceDelivery = true
        };

        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionRequest);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        return subscription;
    }
}

import (
	"context"
	"fmt"
	"io"

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

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

	pbSub := &pubsubpb.Subscription{
		Name:                      subscription,
		Topic:                     topic,
		EnableExactlyOnceDelivery: true,
	}
	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, pbSub)
	if err != nil {
		return fmt.Errorf("failed to create exactly once sub: %w", err)
	}
	fmt.Fprintf(w, "Created a subscription with exactly once delivery enabled: %v\n", sub)
	return nil
}

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

public class CreateSubscriptionWithExactlyOnceDelivery {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";

    createSubscriptionWithExactlyOnceDeliveryExample(projectId, topicId, subscriptionId);
  }

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

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

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  // Enable exactly once delivery in the subscription.
                  .setEnableExactlyOnceDelivery(true)
                  .build());

      System.out.println(
          "Created a subscription with exactly once delivery enabled: "
              + subscription.getAllFields());
    }
  }
}

from google.cloud import pubsub_v1

# TODO(developer): Choose an existing topic.
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

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)

with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "enable_exactly_once_delivery": True,
        }
    )
    print(
        f"Created subscription with exactly once delivery enabled: {subscription}"
    )

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// 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 createSubscriptionWithExactlyOnceDelivery(
  topicNameOrId,
  subscriptionNameOrId,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableExactlyOnceDelivery: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with exactly-once delivery.`,
  );
  console.log(
    'To process messages, remember to check the return value of ackWithResponse().',
  );
}

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';

// Imports the Google Cloud client library
import {PubSub} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createSubscriptionWithExactlyOnceDelivery(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, {
      enableExactlyOnceDelivery: true,
    });
  console.log(
    `Created subscription ${subscriptionNameOrId} with exactly-once delivery.`,
  );
  console.log(
    'To process messages, remember to check the return value of ackWithResponse().',
  );
}

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  enable_exactly_once_delivery: true

puts "Created subscription with exactly once delivery enabled: " \
     "#{subscription_id}"

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription with `Exactly Once Delivery` enabled.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function create_subscription_with_exactly_once_delivery(
    string $projectId,
    string $topicName,
    string $subscriptionName
): void {
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'enableExactlyOnceDelivery' => true
    ]);

    // Exactly Once Delivery status for the subscription
    $status = $subscription->info()['enableExactlyOnceDelivery'];

    printf('Subscription created with exactly once delivery status: %s' . PHP_EOL, $status ? 'true' : 'false');
}

Memantau langganan pengiriman tepat satu kali

Metrik subscription/exactly_once_warning_count mencatat jumlah peristiwa yang dapat menyebabkan pengiriman ulang (valid atau duplikat). Metrik ini menghitung berapa kali Pub/Sub gagal memproses permintaan yang terkait dengan ID pengakuan (permintaan ModifyAckDeadline atau acknowledgment). Alasan kegagalan dapat berupa berbasis server atau klien. Misalnya, jika lapisan persistensi yang digunakan untuk mempertahankan informasi pengiriman tepat satu kali tidak tersedia, maka peristiwa tersebut akan menjadi peristiwa berbasis server. Jika klien mencoba mengonfirmasi pesan dengan ID konfirmasi yang tidak valid, hal ini akan menjadi peristiwa berbasis klien.

Memahami metrik

subscription/exactly_once_warning_count mencatat peristiwa yang mungkin atau mungkin tidak menyebabkan pengiriman ulang yang sebenarnya dan dapat menjadi tidak relevan berdasarkan perilaku klien. Misalnya: permintaan acknowledgment atau ModifyAckDeadline yang berulang dengan ID konfirmasi yang tidak valid akan meningkatkan metrik berulang kali.

Metrik berikut juga berguna untuk memahami perilaku klien:

• Metrik subscription/expired_ack_deadlines_count menampilkan jumlah masa berlaku ID konfirmasi yang berakhir. Masa berlaku ID pengakuan dapat menyebabkan kegagalan untuk permintaan ModifyAckDeadline dan acknowledgment.

• service.serviceruntime.googleapis.com/api/request_count dapat digunakan untuk mencatat kegagalan permintaan ModifyAckDeadline atau acknowledgment jika permintaan mencapai Trusted Cloud by S3NS tetapi tidak mencapai Pub/Sub. Ada kegagalan yang tidak akan dicatat oleh metrik ini, misalnya, saat klien terputus dari Trusted Cloud by S3NS.

Pada sebagian besar kasus peristiwa kegagalan yang dapat dicoba lagi, library klien yang didukung akan mencoba lagi permintaan secara otomatis.

Kuota

Langganan pengiriman tepat satu kali tunduk pada persyaratan kuota tambahan. Kuota ini diterapkan pada:

• Jumlah pesan yang digunakan dari langganan dengan pengiriman tepat satu kali diaktifkan per wilayah.
• Jumlah pesan yang dikonfirmasi atau yang batas waktunya diperpanjang saat menggunakan langganan dengan pengiriman tepat satu kali yang diaktifkan per region.

Untuk mengetahui informasi selengkapnya terkait kuota ini, lihat tabel dalam topik Kuota.

Pengiriman tepat satu kali dan langganan yang diurutkan

Pub/Sub mendukung pengiriman tepat satu kali dengan pengiriman berurutan.

Saat menggunakan pengurutan dengan pengiriman tepat satu kali, Pub/Sub mengharapkan pengakuan dalam urutan. Jika konfirmasi tidak berurutan, layanan akan gagal memenuhi permintaan dengan error sementara. Jika batas waktu konfirmasi berakhir sebelum konfirmasi sesuai urutan untuk pengiriman, klien akan menerima pengiriman ulang pesan. Oleh karena itu, saat Anda menggunakan pengurutan dengan pengiriman tepat satu kali, throughput klien dibatasi hingga urutan ribuan pesan per detik.

Pengiriman tepat satu kali dan langganan push

Pub/Sub mendukung pengiriman tepat satu kali hanya dengan langganan pull.

Klien yang menggunakan pesan dari langganan push mengonfirmasi pesan dengan merespons permintaan push dengan respons yang berhasil. Namun, klien tidak tahu apakah langganan Pub/Sub menerima respons dan memprosesnya. Hal ini berbeda dengan langganan pull, di mana permintaan konfirmasi dimulai oleh klien dan langganan Pub/Sub merespons jika permintaan berhasil diproses. Karena itu, semantik pengiriman tepat satu kali tidak selaras dengan baik dengan langganan push.

Hal untuk diketahui

• Jika batas waktu konfirmasi tidak ditentukan pada waktu CreateSubscription, langganan yang mengaktifkan pengiriman tepat satu kali akan memiliki batas waktu konfirmasi default 60 detik.

• Batas waktu konfirmasi default yang lebih lama bermanfaat untuk menghindari pengiriman ulang yang disebabkan oleh peristiwa jaringan. Library klien yang didukung tidak menggunakan batas waktu konfirmasi langganan default.

• Langganan pengiriman tepat satu kali memiliki latensi publish-to-subscribe yang jauh lebih tinggi dibandingkan dengan langganan reguler.

• Jika Anda memerlukan throughput tinggi, klien pengiriman tepat satu kali juga harus menggunakan tarikan streaming.

• Langganan dapat menerima beberapa salinan pesan yang sama karena duplikat sisi publikasi, meskipun pengiriman tepat satu kali diaktifkan. Duplikat sisi publikasi dapat disebabkan oleh beberapa percobaan ulang publikasi unik oleh klien publikasi atau layanan Pub/Sub. Beberapa publikasi unik oleh klien penerbitan, di seluruh percobaan ulang, menyebabkan pengiriman ulang dengan ID pesan yang berbeda. Beberapa publikasi unik oleh layanan Pub/Sub, untuk merespons permintaan publikasi klien, menyebabkan pengiriman ulang dengan ID pesan yang sama.

• Anda dapat mencoba lagi kegagalan di subscription/exactly_once_warning_count dan library klien yang didukung akan mencoba lagi kegagalan ini secara otomatis. Namun, kegagalan yang terkait dengan ID konfirmasi yang tidak valid tidak dapat dicoba lagi.