此页面由 Cloud Translation API 翻译。

仅传送一次

本页面介绍了如何使用“正好一次”来接收和确认消息语义信息。只有拉取订阅类型支持“正好一次”传送，包括使用 StreamingPull API。

推送和导出订阅不支持“正好一次”传送。

仅传送一次

Pub/Sub 支持在云区域内、基于 Pub/Sub 定义的唯一消息 ID。

启用此功能后，Pub/Sub 将提供以下内容：

成功确认消息后，不会重新传送。
当邮件未完成时，系统不会重新递送。将消息视为未完成，直到确认时限结束或消息已确认。
如果存在多次有效提交，由于存在确认截止期限到期或客户端发起的否定确认，仅限最新的确认 ID 可用于确认消息。包含之前的确认 ID 失败。

重新提交与重复提交

了解预期结果与预期结果之间的区别很重要重新提交。

由于客户发起的负面事件，可能会发生重新提交确认消息，或者当客户端不扩展确认时消息的截止时间。重新提交被视为有效，且系统按预期运行。

要排查重新提交问题，请参阅处理重复内容。
重复项是指在成功确认后重新发送的消息或确认截止期限之前。
重新递送的邮件两次尝试保留相同的邮件 ID。

启用了“仅传送一次”功能的订阅不会收到重复的消息送货。

客户端库中的“正好一次”传送支持

支持的客户端库具有用于确认的接口包含回复（例如：Go）。您可以使用此接口检查确认请求是否成功。如果确认请求成功，则保证客户端不会获得重新提交。如果确认请求失败，客户可能会需要重新提交。
客户端也可以在不使用确认接口的情况下使用受支持的客户端库。不过，在这种情况下确认失败会导致消息静默地重新提交。
支持的客户端库具有用于设置最低数量要求的接口租期延期时间（例如： Go)。您必须将最短租期延期的值设置为较大的数字以避免任何与网络相关的确认过期。最大值设置为 600 秒。

与精确一次传送相关的变量的默认值和范围，以及变量的名称可能会因客户端库而异。对于例如，在 Java 客户端库中，以下变量控制一次性交付。

变量	说明	值
`setEnableExactlyOnceDelivery`	启用或停用“正好一次”投放。	true 或 false，默认值=false
`minDurationPerAckExtension`	用于延长修改确认时限的最短时间（以秒为单位）。	范围=0 到 600 默认值=无
`maxDurationPerAckExtension`	用于延长修改确认时限的最长时间（以秒为单位）。	范围=0 到 600 默认值=无

对于仅传送一次，modifyAckDeadline 或 acknowledgment 向 Pub/Sub 发出的请求失败。在此类在这种情况下，服务会将过期的确认 ID 视为无效，因为较新的投放可能已经在进行中。这是出于正好一次的设计。然后，您会看到 acknowledgment 和 ModifyAckDeadline 请求返回一个 INVALID_ARGUMENT 响应。停用“恰好一次”传送后，如果确认 ID 已过期，这些请求会返回 OK。

为了确保 acknowledgment 和 ModifyAckDeadline 请求有效请考虑将 minDurationPerAckExtension 到较大的数字。

地区注意事项

仅传送一次保证仅适用于订阅者在同一区域内连接到服务的情况。如果您的订阅者应用分布于则可能会导致重复递送邮件，即使启用“正好一次”投放发布者可以向任意区域保证仅有一次。

当您在 Google Cloud 中运行自己的应用时，连接到同一区域中的 Pub/Sub 端点。因此，在 Google Cloud 内的单个区域中运行应用通常可以确保您与单个区域进行互动。

在 Google Cloud 之外运行订阅者应用时还是在多个区域，您可以保证连接到单个区域通过在配置 Pub/Sub 时使用位置端点客户端。Pub/Sub 的所有位置端点均指向单个区域。如需详细了解位置端点，请参阅 Pub/Sub 端点。如需查看 Pub/Sub 的所有位置端点列表，请参阅位置端点列表。

创建“仅传送一次”的订阅

您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 创建仅传送一次的订阅。

拉取订阅

控制台

如需创建具有正好一次传送的拉取订阅，请按照以下步骤操作：

在 Google Cloud 控制台中，进入订阅页面。

前往订阅页面。
点击创建订阅。
输入订阅 ID。
从下拉菜单中选择或创建一个主题。

订阅将接收来自该主题的消息。
在仅传送一次部分，选择启用仅传送一次。
点击创建。

gcloud

如需创建具有正好一次传送的拉取订阅，请使用 gcloud pubsub subscriptions create 命令：--enable-exactly-once-delivery

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

替换以下内容：

SUBSCRIPTION_ID：要创建的订阅的 ID
TOPIC_ID：要附加到订阅的主题的 ID

REST

如需创建“仅传送一次”的订阅，请使用 projects.subscriptions.create 方法。

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

替换以下内容：

PROJECT_ID：要在其中创建订阅的项目的 ID
SUBSCRIPTION_ID：要创建的订阅的 ID

如需创建具有正好一次传送的拉取订阅，请指定以下代码：

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

替换以下内容：

PROJECT_ID：包含主题的项目的 ID
TOPIC_ID：要附加到订阅的主题的 ID

C++

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 C++ 设置说明进行操作。如需了解详情，请参阅 Pub/Sub C++ API 参考文档。

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id) {
  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";
}

C#

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 C# 设置说明进行操作。如需了解详情，请参阅 Pub/Sub C# API 参考文档。


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;
    }
}

Go

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Go 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Go API 参考文档。

import (
	"context"
	"fmt"
	"io"

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

func createSubscriptionWithExactlyOnceDelivery(w io.Writer, projectID, subID string, topic *pubsub.Topic) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.CreateSubscription(ctx, subID, pubsub.SubscriptionConfig{
		Topic:                     topic,
		EnableExactlyOnceDelivery: true,
	})
	if err != nil {
		return err
	}
	fmt.Fprintf(w, "Created a subscription with exactly once delivery enabled: %v\n", sub)
	return nil
}

Java

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Java 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Java API 参考文档。

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());
    }
  }
}

Python

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Python 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Python API 参考文档。

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}"
    )

Node.js

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Node.js API 参考文档。

/**
 * 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().'
  );
}

Node.js

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Node.js API 参考文档。

/**
 * 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().'
  );
}

Ruby

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Ruby 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Ruby API 参考文档。

require "google/cloud/pubsub"

# Shows how to create a new subscription with exactly once delivery enabled
class PubsubCreateSubscriptionWithExactlyOnceDelivery
  def create_subscription_with_exactly_once_delivery project_id:, topic_id:, subscription_id:
    pubsub = Google::Cloud::Pubsub.new project_id: project_id
    topic = pubsub.topic topic_id
    subscription = topic.subscribe subscription_id, enable_exactly_once_delivery: true
    puts "Created subscription with exactly once delivery enabled: #{subscription_id}"
  end

  def self.run
    # TODO(developer): Replace these variables before running the sample.
    project_id = "your-project-id"
    topic_id = "your-topic-id"
    subscription_id = "id-for-new-subcription"
    pubsub_create_subscription_with_exactly_once_delivery = PubsubCreateSubscriptionWithExactlyOnceDelivery.new
    pubsub_create_subscription_with_exactly_once_delivery.create_subscription_with_exactly_once_delivery(
      project_id: project_id,
      topic_id: topic_id,
      subscription_id: subscription_id
    )
  end
end

if $PROGRAM_NAME == __FILE__
  PubsubCreateSubscriptionWithExactlyOnceDelivery.run
end

PHP

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 PHP 设置说明进行操作。如需了解详情，请参阅 Pub/Sub PHP API 参考文档。

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');
}

使用“仅传送一次”消息传送方式进行订阅

以下是使用客户端库订阅“正好一次”传送的一些代码示例。