Pub/Sub Lite 메시지를 Pub/Sub로 내보내기

이 문서에서는 Pub/Sub에 Pub/Sub Lite 메시지를 자동으로 내보내도록 설정하는 방법을 설명합니다.

이 기능을 사용할 수 있는 몇 가지 시나리오는 다음과 같습니다.

  • Pub/Sub Lite와 Pub/Sub를 함께 사용하는 워크로드 간에 상호운용합니다.
  • Pub/Sub Lite 워크로드를 Pub/Sub로 마이그레이션합니다.
  • Pub/Sub Lite를 기반으로 하는 기존 애플리케이션에서 푸시 구독 및 필터링과 같은 고급 Pub/Sub 기능을 사용합니다.
  • 여러 데이터 파이프라인을 통합합니다.

개요

Pub/Sub Lite에서 Pub/Sub로 메시지를 내보내려면 내보내기 구독이라는 특수한 유형의 구독을 만듭니다. 내보내기 구독은 Lite 주제에서 메시지를 수신하여 Pub/Sub 메시지로 변환하고 변환된 메시지를 대상 Pub/Sub 주제로 전송합니다.

Pub/Sub Lite 메시지 내보내기 다이어그램

Lite 주제에서는 내보내기 구독과 표준 구독을 조합할 수 있습니다. 두 구독 유형은 할당량 사용과 예약 처리량 측면에서 동일합니다. 내보내기 구독은 Lite 구독 처리량 용량을 소비하며 Pub/Sub 게시 처리량에 대한 요금이 청구됩니다.

내보내기 구독은 Lite 주제를 정확히 하나의 Pub/Sub 주제에 연결합니다. 하지만 Lite 주제에는 서로 다른 Pub/Sub 주제에 연결되는 내보내기 구독이 여러 개 있을 수 있습니다(팬아웃 아키텍처). 여러 Lite 주제에서 동일한 Pub/Sub 주제로 내보낼 수도 있습니다(팬인 아키텍처).

인증

내보내기 구독은 Pub/Sub Lite 및 Pub/Sub 리소스 모두에 액세스합니다. 내보내기 구독을 만들려면 다음 권한이 필요합니다.

  • pubsublite.subscriptions.create. 다음과 같은 사전 정의된 역할에 이 권한이 포함되어 있습니다.

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

    Pub/Sub Lite 액세스 제어를 참조하세요.

  • pubsub.topics.get. 다음과 같은 사전 정의된 역할에 이 권한이 포함되어 있습니다.

    • roles/pubsub.admin
    • roles/pubsub.editor
    • roles/pubsub.viewer

    Pub/Sub 액세스 제어를 참조하세요.

서비스 에이전트

내보내기 구독은 사용자를 대신하여 Pub/Sub 주제에 게시합니다. 이를 위해 서비스 에이전트를 사용합니다.

프로젝트에서 첫 번째 내보내기 구독을 만들면 Pub/Sub Lite 서비스 에이전트가 자동으로 생성됩니다. 동일한 프로젝트에 추가 내보내기 구독을 만들면 동일한 서비스 에이전트가 사용됩니다. 서비스 에이전트에는 다음과 같은 이름 지정 스키마가 있습니다. service-<your_project_number>@gcp-sa-pubsublite.iam.gserviceaccount.com

서비스 에이전트는 내보내기 구독과 동일한 프로젝트 내의 모든 Pub/Sub 및 Pub/Sub Lite 주제에 게시할 수 있는 권한으로 생성됩니다. 대상 Pub/Sub 주제가 내보내기 구독과 다른 프로젝트에 있는 경우 Pub/Sub 게시자 역할(roles/pubsub.publisher)을 추가하여 서비스 에이전트에 추가 권한을 부여해야 합니다. 전체 프로젝트 또는 개별 주제에 대한 권한을 부여할 수 있습니다. 최소 권한의 원칙에 따라 주제 수준에서 권한을 부여하는 것이 좋습니다.

자세한 내용은 Google Cloud 콘솔을 통한 액세스 제어를 참조하세요. 또한 gcloud projects add-iam-policy-binding 명령어를 사용하여 IAM 역할을 추가할 수 있습니다.

gcloud pubsub topics add-iam-policy-binding TOPIC_NAME \
 --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsublite.iam.gserviceaccount.com
 --role=roles/pubsub.publisher

다음을 바꿉니다.

  • TOPIC_NAME: IAM 정책 바인딩을 추가할 대상 Pub/Sub 주제의 이름입니다.
  • PROJECT_NUMBER: Pub/Sub Lite 내보내기 구독 프로젝트의 프로젝트 번호입니다.

내보내기 구독 만들기

Google Cloud 콘솔, Google Cloud CLI, Pub/Sub Lite API를 사용하여 Lite 내보내기 구독을 만들 수 있습니다.

Lite 내보내기 구독은 연결된 Lite 주제와 동일한 프로젝트 및 위치에 있어야 합니다. Lite 주제를 만들려면 Lite 주제 만들기 및 관리를 참조하세요.

Lite 주제에 내보내기 구독을 연결하는 경우 Lite 주제에 게시된 모든 메시지가 Pub/Sub와 호환되는지 확인합니다. 자세한 내용은 메시지 호환성을 참조하세요.

생성된 후에는 내보내기 구독을 표준 구독으로 또는 그 반대로 변경할 수 없습니다.

콘솔

  1. 라이트 구독 페이지로 이동

    라이트 구독으로 이동

  2. 라이트 구독 만들기를 클릭합니다.

  3. Lite 구독 ID를 입력합니다.

  4. 메시지를 수신할 라이트 주제를 선택합니다.

  5. 메시지 즉시 전송 또는 저장 후 메시지 전송을 선택합니다.

  6. 시작 오프셋 유형을 선택합니다.

  7. Pub/Sub 주제로 내보내기를 선택합니다.

  8. 대상 주제 목록에서 내보낸 Lite 메시지를 수신할 Pub/Sub 주제를 선택합니다.

  9. 선택사항. 데드 레터 주제를 지정합니다.

    1. 데드 레터 처리 사용 설정 체크박스를 선택합니다.
    2. 데드 레터 주제로 사용할 Lite 주제를 선택하거나 Lite 주제 만들기를 클릭하여 새 데드 레터 주제를 만듭니다. 데드 레터 주제는 내보내기 구독과 동일한 위치(영역 또는 리전) 및 프로젝트에 있어야 합니다.

  10. 만들기를 클릭합니다.

gcloud

내보내기 구독을 만들려면 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

다음을 바꿉니다.

  • SUBSCRIPTION_ID: 만들려는 Lite 구독의 ID입니다.
  • LOCATION: Lite 구독의 위치입니다.
  • TOPIC_ID: Lite 구독에 연결할 Lite 주제의 ID입니다.
  • PUBSUB_TOPIC_NAME: 내보낼 Pub/Sub 주제의 이름입니다. 주제가 다른 프로젝트에 있으면 전체 이름(projects/my-project-id/topics/my-topic-id)을 지정합니다.
  • DEAD_LETTER_TOPIC_ID: 선택사항. 데드 레터 주제로 사용할 Lite 주제의 ID입니다. 데드 레터 주제는 내보내기 구독과 동일한 위치(영역 또는 리전) 및 프로젝트에 있어야 합니다.
  • DESIRED_STATE: 선택사항. 구독의 시작 상태입니다. 다음과 같은 값이 지원됩니다.
    • active: 구독이 Lite 메시지를 Pub/Sub로 내보냅니다. (기본값)
    • paused: Lite 메시지 내보내기가 정지됩니다.

요청이 성공하면 명령줄에 확인 메시지가 표시됩니다.

Created [SUBSCRIPTION_ID].

프로토콜

Lite 내보내기 구독을 만들려면 다음과 같이 POST 요청을 보냅니다.

POST https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/LOCATION/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer $(gcloud auth print-access-token)

다음을 바꿉니다.

  • REGION: Lite 구독을 저장할 리전입니다.
  • PROJECT_NUMBER: Lite 구독을 만들 프로젝트의 프로젝트 번호입니다.
  • LOCATION: Pub/Sub Lite가 지원하는 위치의 이름입니다.
  • SUBSCRIPTION_ID: Lite 구독의 ID입니다.

요청 본문에 다음 필드를 지정합니다.

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

다음을 바꿉니다.

  • DELIVERY_REQUIREMENT: 전송 요구사항(DELIVER_AFTER_STORED 또는 DELIVER_IMMEDIATELY)입니다.
  • DESIRED_STATE: 구독의 시작 상태입니다. 다음과 같은 값이 지원됩니다.
    • ACTIVE: 구독이 Lite 메시지를 Pub/Sub로 내보냅니다.
    • PAUSED: Lite 메시지 내보내기가 정지됩니다.
  • DEAD_LETTER_TOPIC_ID: 데드 레터 주제로 사용할 기존 Lite 주제의 ID입니다. 주제는 내보내기 구독 자체와 동일한 위치(영역 또는 리전) 및 프로젝트에 있어야 합니다.
  • PUBSUB_TOPIC_NAME: 내보낼 Pub/Sub 주제의 이름입니다. 예시 형식: projects/my-project-id/topics/my-topic-id

요청이 성공하는 경우 응답은 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

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

이 샘플을 실행하기 전에 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

이 샘플을 실행하기 전에 Pub/Sub Lite 클라이언트 라이브러리의 Python 설정 안내를 따르세요.

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

내보내기 구독 업데이트

Google Cloud 콘솔, Google Cloud CLI, Pub/Sub Lite API를 사용하여 Lite 구독을 업데이트할 수 있습니다. 새 설정이 적용되는 데 최대 30초가 걸릴 수 있습니다.

콘솔

  1. 라이트 구독 페이지로 이동

    라이트 구독으로 이동

  2. 라이트 구독 ID를 클릭합니다.

  3. 라이트 구독 세부정보 페이지에서 수정을 클릭합니다.

gCloud

라이트 구독을 업데이트하려면 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

다음을 바꿉니다.

  • SUBSCRIPTION_ID: Lite 구독의 ID입니다.
  • LOCATION: Lite 구독의 위치입니다.
  • DELIVERY_REQUIREMENT: 선택사항. 전송 요구사항(deliver-after-stored 또는 deliver-immediately)입니다.
  • PUBSUB_TOPIC_NAME: 선택사항. 내보낼 Pub/Sub 주제의 이름입니다. 주제가 다른 프로젝트에 있으면 전체 이름(projects/my-project-id/topics/my-topic-id)을 지정합니다.
  • DEAD_LETTER_TOPIC_ID: 데드 레터 주제로 사용할 기존 Lite 주제의 ID입니다. 주제는 내보내기 구독 자체와 동일한 위치(영역 또는 리전) 및 프로젝트에 있어야 합니다.
  • DESIRED_STATE: 선택사항. 원하는 구독 상태입니다. 다음과 같은 값이 지원됩니다.
    • active: 구독이 Lite 메시지를 Pub/Sub로 내보냅니다. (기본값)
    • paused: 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

프로토콜

라이트 구독을 업데이트하려면 다음과 같이 PATCH 요청을 보냅니다.

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)

다음을 바꿉니다.

  • REGION: Lite 구독이 생성된 리전입니다.
  • PROJECT_NUMBER: Lite 구독이 생성된 프로젝트의 프로젝트 번호입니다.
  • LOCATION: Lite 구독이 생성된 위치입니다.
  • SUBSCRIPTION_ID: Lite 구독의 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"
      }
  }
}

다음을 바꿉니다.

  • DELIVERY_REQUIREMENT: 전송 요구사항(DELIVER_AFTER_STORED 또는 DELIVER_IMMEDIATELY)입니다.
  • DESIRED_STATE: 원하는 구독 상태입니다. 다음과 같은 값이 지원됩니다.
    • ACTIVE: 구독이 Lite 메시지를 Pub/Sub로 내보냅니다.
    • PAUSED: Lite 메시지 내보내기가 정지됩니다.
  • DEAD_LETTER_TOPIC_ID: 데드 레터 주제로 사용할 기존 Lite 주제의 ID입니다. 주제는 내보내기 구독 자체와 동일한 위치(영역 또는 리전) 및 프로젝트에 있어야 합니다.
  • PUBSUB_TOPIC_NAME: 대상 Pub/Sub 주제의 이름입니다. 예시 형식: projects/my-project-id/topics/my-topic-id

요청이 성공하는 경우 응답은 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",
}

내보내기 구독 일시중지 또는 시작

내보내기 구독에는 다음 두 값 중 하나를 갖는 원하는 상태라는 설정이 있습니다.

  • 활성: 구독이 Lite 메시지를 Pub/Sub로 내보냅니다.
  • 일시중지: Lite 메시지 내보내기가 정지됩니다.

Google Cloud 콘솔에서 원하는 상태를 변경하려면 다음 안내를 따르세요.

  1. 라이트 구독 페이지로 이동

    라이트 구독으로 이동

  2. 라이트 구독 ID를 클릭합니다.

  3. Lite 구독 세부정보 페이지에서 일시중지 또는 시작을 클릭합니다.

Google Cloud CLI 또는 Pub/Sub Lite API를 사용하여 원하는 상태를 업데이트할 수도 있습니다. 내보내기 구독 업데이트를 참조하세요.

권장사항

이 섹션에서는 내보내기 구독을 사용할 때의 몇 가지 권장사항을 설명합니다.

예약

구독의 처리량 용량을 명시적으로 설정하는 대신 예약과 함께 내보내기 구독을 사용하는 것이 좋습니다.

메시지 호환성

Pub/Sub Lite 메시지가 Pub/Sub와 호환되지 않으면 내보내기 구독이 메시지를 Pub/Sub에 게시하지 않습니다. 대신 데드 레터 주제에 메시지를 배치합니다(할당된 경우). 데드 레터 주제가 할당되지 않은 경우에는 호환되지 않는 메시지가 삭제됩니다.

Lite 주제에 메시지를 게시할 때 다음 호환성 문제에 유의하세요.

  • 키. Pub/Sub Lite 키는 bytes 유형이고 Pub/Sub 순서 키는 string 유형입니다. 호환되려면 Pub/Sub Lite 키에 UTF-8 문자만 포함되어야 합니다.

  • 속성. 메시지 속성에는 다음과 같은 요구사항이 있습니다.

    • 호환되려면 모든 Pub/Sub Lite 메시지 속성에 단일 값이 있어야 합니다. Pub/Sub Lite는 여러 값이 있는 메시지 속성을 지원하지만 Pub/Sub는 단일 값 속성만 지원합니다.
    • 메시지 속성이 메시지당 최대 속성, 속성당 최대 키, 속성당 값 크기를 포함한 Pub/Sub 메시지 한도를 초과하면 안 됩니다.

데드 레터 주제

호환되지 않는 메시지를 보관하고 처리하려면 데드 레터 주제를 사용하는 것이 좋습니다. 내보내기 구독을 만들 때 데드 레터 주제를 할당하거나 기존 내보내기 구독을 업데이트하여 데드 레터 주제를 사용할 수 있습니다. 구독이 Pub/Sub와 호환되지 않는 메시지를 수신하면 메시지를 데드 레터 주제에 게시합니다.

데드 레터 주제는 일반 Pub/Sub Lite 주제입니다. 내보내기 구독과 동일한 위치 및 프로젝트에 있어야 하며 소스 주제와 다른 주제여야 합니다.

일반적으로 데드 레터 주제는 처리량 사용률이 낮습니다. 따라서 처리량을 주제에 할당하는 대신 데드 레터 주제에 예약을 할당하는 것이 좋습니다.

전송 오류

내보내기 구독은 호환되는 모든 메시지를 대상 Pub/Sub 주제로 전송하려고 시도합니다. 메시지 전송이 실패하면 내보내기 구독이 정지됩니다. 오류 카테고리를 찾으려면 subscription/export_status 측정항목을 확인합니다. 다음 값은 오류를 나타냅니다.

  • PERMISSION_DENIED: 메시지를 내보낼 권한이 없습니다.
  • NOT_FOUND: 하나 이상의 리소스를 찾을 수 없습니다. 예를 들면 대상 주제가 존재하지 않습니다.

문제 해결에 대한 자세한 내용은 내보내기 구독 문제 해결을 참조하세요.

오류를 해결한 후 정기적인 재시도에 따라 내보내기 구독이 자동으로 다시 시작됩니다.

가격 책정

내보내기 구독에서 사용하는 Pub/Sub Lite 및 Pub/Sub 리소스에 대한 요금이 부과됩니다. 특히 Pub/Sub Lite 주제에 대해 구성된 Pub/Sub Lite 구독에 할당된 구독 처리량 및 스토리지에 대한 요금이 부과됩니다. 대상 Pub/Sub 주제에 게시하는 경우에도 요금이 청구됩니다. Pub/Sub 가격 책정을 참조하세요.

내보내기 기능을 사용하는 경우에는 추가 요금이 청구되지 않으며 Pub/Sub Lite 내보내기 구독과 표준 구독 간에 가격 차이가 없습니다.

내보내기 구독 문제 해결

이 섹션에서는 내보내기 구독 문제 몇 가지를 해결하는 팁을 설명합니다.

내보내기 구독이 일시중지됨

구독이 일시중지되면 메시지가 내보내지지 않습니다.

이 문제를 감지하려면 다음 안내를 따르세요.

  • Google Cloud 콘솔: 구독 세부정보를 확인합니다. 구독이 일시중지된 경우 원하는 상태와 현재 상태가 Paused입니다.

  • 측정항목: subscription/export_status 측정항목이 PAUSED입니다.

이 문제를 해결하려면 구독을 시작합니다.

대상 주제 또는 데드 레터 주제가 삭제됨

내보내기 구독에 연결된 Pub/Sub 주제를 삭제하거나 데드 레터 주제를 삭제하면 오류가 발생합니다.

이 문제를 감지하려면 다음 안내를 따르세요.

  • Google Cloud 콘솔: 구독 세부정보를 확인합니다. 주제가 삭제된 경우 현재 상태가 Not found입니다.

  • 측정항목: subscription/export_status 측정항목입니다. 주제가 삭제된 경우 값이 NOT_FOUND입니다.

이 문제를 해결하려면 대상 Pub/Sub 주제와 데드 레터 주제(구성된 경우)를 확인합니다.

대상 Pub/Sub가 삭제되었으면 동일한 이름으로 주제를 다시 만듭니다. 내보내기 구독에서 권한이 변경되지 않았다고 가정하고 게시를 재개합니다.

데드 레터 주제가 삭제된 경우 새 데드 레터 주제를 만들고 이를 참조하도록 내보내기 구독을 업데이트합니다.

호환되지 않는 메시지

메시지가 Pub/Sub와 호환되지 않으면 메시지를 내보내지 않습니다.

이 문제를 감지하려면 다음 안내를 따르세요.

  • 측정항목: subscription/unexportable_message_count 측정항목은 내보낼 수 없는 호환되지 않는 메시지 수를 보여줍니다.

이 문제를 해결하려면 데드 레터 주제를 사용하여 호환되지 않는 메시지를 보관합니다. 메시지를 검사하여 원인을 확인한 후 필요한 경우 메시지를 변환하고 다시 게시합니다. 메시지 호환성을 참조하세요.

내보내기가 제한됨

이 문제를 감지하려면 다음 안내를 따르세요.

  • 측정항목: subscription/flow_control_status 측정항목은 미해결 바이트 또는 메시지의 파티션당 한도에 도달했음을 나타내는 NO_CLIENT_TOKENS의 흐름 제어 이유를 보여줍니다. 이 문제가 해결될 때까지 연결된 내보내기 구독의 백로그가 증가합니다.

이 오류에는 가능한 근본 원인이 몇 가지 있습니다. 가능한 원인은 대부분 백엔드에서 발생하지만 다음을 확인하세요.

  • 키당 1MiB/초 미만의 속도로 동일한 키를 공유하는 Lite 메시지를 게시하는지 확인합니다. 내보내기 구독은 Lite 메시지 키를 Pub/Sub 순서 키로 작성하며, Pub/Sub에는 각 순서 키에 1MiB/초의 한도가 있습니다. 이 한도를 초과하면 제한이 발생할 수 있습니다.

이 작업을 수행할 권한이 없는 사용자

Pub/Sub Lite 서비스 에이전트에는 대상 Pub/Sub 주제에 게시할 권한이 있어야 합니다.

이 문제를 감지하려면 다음 안내를 따르세요.

  • Google Cloud 콘솔: 구독 세부정보를 확인합니다. 권한 오류가 있는 경우 현재 상태가 Permission denied입니다.

  • 측정항목: subscription/export_status 측정항목이 PERMISSON_DENIED입니다.

예를 들어 다음 경우에 이 오류가 발생할 수 있습니다.

  • Pub/Sub Lite 서비스 에이전트에 다른 프로젝트의 대상 Pub/Sub 주제에 메시지를 게시하기 위한 올바른 권한 또는 역할이 없습니다.
  • 내보내기 구독 상위 프로젝트의 IAM 정책에서 서비스 에이전트가 삭제되었습니다.
  • Pub/Sub Lite 서비스 에이전트를 아직 설정하는 중입니다. 서비스 에이전트는 프로젝트에서 첫 번째 내보내기 구독을 만들 때 자동으로 생성됩니다. 권한 오류는 10분 이내에 자동으로 해결됩니다.

문제를 해결하려면 서비스 에이전트에 올바른 권한 또는 역할이 부여되었는지 확인합니다. 서비스 에이전트를 참조하세요.

다음 단계

Pub/Sub 또는 Pub/Sub Lite 선택