1회만 전송

이 페이지에서는 Pub/Sub의 1회만 전송 기능을 사용하여 메시지를 수신하고 확인하는 방법을 설명합니다. 이 기능을 사용하면 메시지의 중복 처리를 추적하고 방지할 수 있습니다. 기능이 사용 설정되면 Pub/Sub에서 다음 시맨틱스를 제공합니다.

구독자는 메시지 확인이 성공했는지 확인할 수 있습니다.
메시지가 성공적으로 확인되면 다시 전송되지 않습니다.
메시지가 대기 중일 때는 다시 전송되지 않습니다. 확인 기한이 만료되거나 메시지가 확인될 때까지 메시지가 대기 중으로 고려됩니다.
전송이 여러 번 유효하게 진행된 경우 확인 기한 만료 또는 클라이언트에서 시작된 부정 확인으로 인해 최신 확인 ID만 사용해서 메시지를 확인할 수 있습니다. 이전 확인 ID가 있는 요청은 실패합니다.

1회만 전송 기능을 사용 설정하면 구독자는 다음 가이드라인에 따라 메시지가 한 번만 처리되도록 할 수 있습니다.

확인 기한 내에 메시지를 확인합니다.
메시지가 확인될 때까지 메시지 처리 진행 상황에 관한 정보를 유지합니다.
확인 실패 시 중복 작업을 방지하기 위해 메시지 처리 진행 상황에 관한 정보를 사용합니다.

StreamingPull API를 사용하는 구독자를 포함하여 풀(pull) 구독 유형만 1회만 전송을 지원합니다. 푸시 및 내보내기 구독은 1회만 전송을 지원하지 않습니다.

Pub/Sub는 Pub/Sub에서 정의한 고유 메시지 ID를 기반으로 클라우드 리전 내에서 1회만 전송을 지원합니다.

권장 클라이언트 라이브러리 버전

최고의 성능을 위해 최신 버전의 클라이언트 라이브러리, Python v2.13.6 이상, 자바 v1.120.11 이상, PHP v1.39.0 이상, C# v3.2.0 이상, C++ v2.1.0, Go v1.25.1 이상, Node v3.2.0 이상, Ruby v2.12.1 이상을 사용합니다.

다시 전송과 중복 비교

예상한 재전송과 예기치 않은 재전송의 차이를 이해하는 것이 중요합니다.

클라이언트에서 시작된 메시지에 대한 부정 확인으로 인해 또는 확인 기한 만료 전 클라이언트가 메시지에 대해 확인 기한을 연장하지 않은 경우에 다시 전송이 수행될 수 있습니다. 다시 전송은 유효한 것으로 고려되고 시스템이 의도된 대로 작동합니다.

재전송 문제를 해결하려면 중복 처리를 참조하세요.
중복은 확인이 성공적으로 완료된 후 또는 확인 기한이 만료되기 전에 메시지가 다시 전송될 경우입니다.
재전송된 메일은 재전송 시도 간에 동일한 메시지 ID를 유지합니다.

1회만 전송이 사용 설정된 구독은 중복 전송을 수신하지 않습니다.

클라이언트 라이브러리의 1회만 전송 지원

지원되는 클라이언트 라이브러리에는 응답 확인을 위한 인터페이스가 있습니다(예: Go). 이 인터페이스를 사용하여 확인 요청이 성공했는지 확인할 수 있습니다. 확인 요청이 성공하면 클라이언트에 재전송이 수신되지 않습니다. 확인 요청이 실패하면 클라이언트가 재전송을 예상할 수 있습니다.
클라이언트가 확인 인터페이스 없이 지원되는 클라이언트 라이브러리를 사용할 수도 있습니다. 그러나 이러한 경우에는 확인 실패로 인해 메시지가 자동으로 재전송될 수 있습니다.
지원되는 클라이언트 라이브러리에는 최소 임대 확장 시간을 설정하기 위한 인터페이스가 포함됩니다(예: Go). 네트워크 관련 확인 만료를 방지하기 위해서는 최소 임대 확장 값을 높은 숫자로 설정해야 합니다. 최댓값은 600초로 설정됩니다.

1회만 전송과 관련된 변수의 기본값과 범위, 변수 이름은 클라이언트 라이브러리마다 다를 수 있습니다. 예를 들어 자바 클라이언트 라이브러리에서는 다음 변수가 1회만 전송을 제어합니다.

변수	설명	값
`setEnableExactlyOnceDelivery`	1회만 전송을 사용 설정 또는 중지합니다.	true 또는 false 기본값=false
`minDurationPerAckExtension`	확인 기한 수정을 연장하는 데 사용할 최소 시간(초)입니다.	범위=0~600 기본값=없음
`maxDurationPerAckExtension`	확인 기한 수정을 연장하는 데 사용할 최대 시간(초)입니다.	범위=0~600 기본값=없음

1회만 전송에서는 확인 ID가 이미 만료된 경우 Pub/Sub에 대한 modifyAckDeadline 또는 acknowledgment 요청이 실패합니다. 이 경우 새 전송이 이미 진행 중일 수 있으므로 서비스에서 만료된 확인 ID를 잘못된 것으로 간주합니다. 이는 1회만 전송의 기본 설정입니다. acknowledgment 및 ModifyAckDeadline 요청이 INVALID_ARGUMENT 응답을 반환합니다. 1회만 전송이 중지되면 확인 ID가 만료된 경우 이러한 요청이 OK를 반환합니다.

acknowledgment 및 ModifyAckDeadline 요청에 유효한 확인 ID가 있는지 확인하려면 minDurationPerAckExtension의 값을 높게 설정합니다.

리전별 고려사항

1회만 전송 보장은 구독자가 동일한 리전의 서비스에 연결할 때만 적용됩니다. 구독자 애플리케이션이 여러 리전에 분산되어 있으면 1회만 전송이 사용 설정되어 있더라도 메시지 전송이 중복될 수 있습니다. 게시자가 모든 리전에 메시지를 전송할 수 있고 1회만 보장이 계속 유지됩니다.

Google Cloud 내에서 애플리케이션을 실행할 때는 기본적으로 동일 리전의 Pub/Sub 엔드포인트에 연결됩니다. 따라서 Google Cloud 내의 단일 리전에서 애플리케이션을 실행하면 일반적으로 단일 리전과 상호작용하도록 보장됩니다.

Google Cloud 외부 또는 여러 리전에서 구독자 애플리케이션을 실행하는 경우 Pub/Sub 클라이언트를 구성할 때 위치별 엔드포인트를 사용하여 단일 리전에 연결하도록 보장할 수 있습니다. Pub/Sub의 모든 위치 엔드포인트는 단일 리전에 연결됩니다. 위치별 엔드포인트에 대한 자세한 내용은 Pub/Sub 엔드포인트를 참조하세요. Pub/Sub의 모든 위치별 엔드포인트 목록은 위치별 엔드포인트 목록을 참조하세요.

1회만 전송 구독 만들기

Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리 또는 Pub/Sub API를 사용하여 1회만 전송 구독을 만들 수 있습니다.

풀 구독

콘솔

1회만 전송 pull 구독을 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 구독 페이지로 이동합니다.

구독 페이지로 이동
구독 만들기를 클릭합니다.
구독 ID를 입력합니다.
드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다.

구독은 주제에서 메시지를 수신합니다.
1회만 전송 섹션에서 1회만 전송 사용 설정을 선택합니다.
만들기를 클릭합니다.

gcloud

1회만 전송 pull 구독을 만들려면 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

1회만 전송 구독을 만들려면 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

1회만 전송 pull 구독을 만들려면 요청 본문에 다음을 지정합니다.

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

자바

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 자바 설정 안내를 따르세요. 자세한 내용은 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

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

1회만 메시지 전송 구독

다음은 클라이언트 라이브러리를 사용하여 1회만 전송 구독을 위한 몇 가지 코드 샘플입니다.