라이트 주제 만들기 및 관리

이 페이지에서는 라이트 주제를 만들고 보고 삭제하는 방법을 설명합니다.

라이트 주제는 메시지를 게시할 수 있는 영역별 리소스입니다. 라이트 주제를 만들 때 메시지를 저장할 영역을 지정해야 합니다.

라이트 주제를 만든 후 라이트 주제에 메시지를 게시하고 라이트 주제에 대한 라이트 구독을 만들고 라이트 주제에서 메시지를 수신할 수 있습니다.

라이트 주제 만들기

라이트 주제를 만들 때 처리량과 스토리지 용량을 설정해야 합니다. 파티션의 수와 용량은 라이트 주제의 용량을 결정합니다.

라이트 주제에는 다음과 같은 속성이 있습니다.

  • 파티션 수: 라이트 주제의 파티션 수입니다.
  • 파티션당 스토리지: 각 파티션의 스토리지 용량(바이트)입니다. 30 GiB~10 TiB의 스토리지 용량을 지정할 수 있습니다.
  • 게시 처리량 용량: 각 파티션의 최대 게시 처리량입니다. 초당 4~16 MiB를 처리량 용량으로 지정할 수 있으며 이 값은 정수여야 합니다. 최상의 결과를 얻으려면 최소한의 게시 처리량으로 라이트 주제를 만드세요. 트래픽이 증가하면 라이트 주제를 업데이트하고 게시 처리량을 늘립니다.
  • 구독 처리량 용량: 각 파티션의 최대 구독 처리량입니다. 초당 4~32 MiB를 처리량 용량으로 지정할 수 있으며 이 값은 정수여야 합니다.

  • 메시지 보관 기간: 라이트 주제가 메시지를 저장하는 최대 시간입니다. 메시지 보관 기간을 지정하지 않으면 스토리지 용량을 초과할 때까지 라이트 주제에 메시지가 저장됩니다.

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub Lite API를 사용하여 라이트 주제를 만들 수 있습니다.

Console

  1. Cloud Console에서 라이트 주제 페이지로 이동합니다.

    라이트 주제 페이지로 이동

  2. 라이트 주제 만들기를 클릭합니다.

  3. 리전과 리전의 영역을 선택합니다.

  4. 이름 섹션에서 라이트 주제 ID를 입력합니다. 라이트 주제 이름에는 라이트 주제 ID, 영역, 프로젝트 번호가 포함됩니다.

  5. 처리량 섹션에서 파티션 수를 입력하여 파티션을 프로비저닝합니다.

  6. 메시지 스토리지 섹션에서 파티션당 스토리지를 입력합니다.

  7. 선택사항: 메시지 보관 섹션에서 스토리지를 사용할 수 있어도 지정된 기간이 지나면 메시지 삭제를 선택하고 보관 기간을 입력합니다.

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

gcloud

라이트 주제를 만들려면 gcloud pubsub lite-topics create 명령어를 사용합니다.

gcloud pubsub lite-topics create TOPIC_ID \
  --zone=ZONE \
  --partitions=NUMBER_OF_PARTITIONS \
  --per-partition-bytes=STORAGE_PER_PARTITION \
  [--message-retention-period=MESSAGE_RETENTION_PERIOD]

다음을 바꿉니다.

  • TOPIC_ID: 라이트 주제의 ID

  • ZONE: Pub/Sub 라이트가 지원하는 영역의 이름

  • NUMBER_OF_PARTITIONS: 라이트 주제의 파티션 수(정수)

  • STORAGE_PER_PARTITION: 각 파티션의 스토리지 용량(예: 30GiB)

  • MESSAGE_RETENTION_PERIOD: 라이트 주제에서 메시지를 저장하는 시간(예: 1d 또는 2w)

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

Created [TOPIC_ID].

프로토콜

라이트 주제를 만들려면 다음과 같이 POST 요청을 보내세요.

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

다음을 바꿉니다.

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

{
  "partitionConfig": {
       "count": NUMBER_OF_PARTITIONS,
       "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
       }
  },
  "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
  },
}

다음을 바꿉니다.

  • NUMBER_OF_PARTITIONS: 라이트 주제의 파티션 수(정수)

  • STORAGE_PER_PARTITION: 각 파티션의 스토리지 용량(예: 30GiB)

  • PUBLISHING_CAPACITY: 각 파티션의 게시 처리량 용량(정수)

  • SUBSCRIBING_CAPACITY: 각 파티션의 구독 처리량 용량(정수)

  • MESSAGE_RETENTION_PERIOD: 라이트 주제에서 메시지를 저장하는 시간(예: 1d 또는 2w)

요청이 성공하는 경우 응답은 JSON 형식의 라이트 주제입니다.

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
       "count": NUMBER_OF_PARTITIONS,
       "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
       }
  },
  "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
  },
}

Go

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참조 문서를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

func createTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1" // see https://cloud.google.com/pubsub/lite/docs/locations
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	const gib = 1 << 30
	// For ranges of fields in TopicConfig, see https://pkg.go.dev/cloud.google.com/go/pubsublite/#TopicConfig
	topic, err := client.CreateTopic(ctx, pubsublite.TopicConfig{
		Name:                       fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID),
		PartitionCount:             2, // Must be >= 1 and cannot decrease after creation.
		PublishCapacityMiBPerSec:   4,
		SubscribeCapacityMiBPerSec: 8,
		PerPartitionBytes:          30 * gib,
		RetentionDuration:          pubsublite.InfiniteRetention,
	})
	if err != nil {
		return fmt.Errorf("client.CreateTopic got err: %v", err)
	}
	fmt.Fprintf(w, "Created topic: %s\n", topic.Name)
	return nil
}

자바

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

import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;
import com.google.cloud.pubsublite.proto.Topic.PartitionConfig;
import com.google.cloud.pubsublite.proto.Topic.RetentionConfig;
import com.google.protobuf.util.Durations;

public class CreateTopicExample {

  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";
    long projectNumber = Long.parseLong("123456789");
    int partitions = 1;

    createTopicExample(cloudRegion, zoneId, projectNumber, topicId, partitions);
  }

  public static void createTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId, int partitions)
      throws Exception {

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    Topic topic =
        Topic.newBuilder()
            .setPartitionConfig(
                PartitionConfig.newBuilder()
                    // Set throughput capacity per partition in MiB/s.
                    .setCapacity(
                        PartitionConfig.Capacity.newBuilder()
                            // Must be 4-16 MiB/s.
                            .setPublishMibPerSec(4)
                            // Must be 4-32 MiB/s.
                            .setSubscribeMibPerSec(8)
                            .build())
                    .setCount(partitions))
            .setRetentionConfig(
                RetentionConfig.newBuilder()
                    // How long messages are retained.
                    .setPeriod(Durations.fromDays(1))
                    // Set storage per partition to 30 GiB. This must be 30 GiB-10 TiB.
                    // If the number of bytes stored in any of the topic's partitions grows
                    // beyond this value, older messages will be dropped to make room for
                    // newer ones, regardless of the value of `period`.
                    .setPerPartitionBytes(30 * 1024 * 1024 * 1024L))
            .setName(topicPath.toString())
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic response = adminClient.createTopic(topic).get();
      System.out.println(response.getAllFields() + "created successfully.");
    }
  }
}

Python

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

from google.api_core.exceptions import AlreadyExists
from google.cloud.pubsublite import AdminClient, Topic
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath
from google.protobuf.duration_pb2 import Duration

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"
# num_partitions = 1

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)
topic = Topic(
    name=str(topic_path),
    partition_config=Topic.PartitionConfig(
        # A topic must have at least one partition.
        count=num_partitions,
        # Set throughput capacity per partition in MiB/s.
        capacity=Topic.PartitionConfig.Capacity(
            # Set publish throughput capacity per partition to 4 MiB/s. Must be >= 4 and <= 16.
            publish_mib_per_sec=4,
            # Set subscribe throughput capacity per partition to 4 MiB/s. Must be >= 4 and <= 32.
            subscribe_mib_per_sec=8,
        ),
    ),
    retention_config=Topic.RetentionConfig(
        # Set storage per partition to 30 GiB. This must be in the range 30 GiB-10TiB.
        # If the number of byptes stored in any of the topic's partitions grows beyond
        # this value, older messages will be dropped to make room for newer ones,
        # regardless of the value of `period`.
        per_partition_bytes=30 * 1024 * 1024 * 1024,
        # Allow messages to be retained for 7 days.
        period=Duration(seconds=60 * 60 * 24 * 7),
    ),
)

client = AdminClient(cloud_region)
try:
    response = client.create_topic(topic)
    print(f"{response.name} created successfully.")
except AlreadyExists:
    print(f"{topic_path} already exists.")

사용 가능한 영역 목록은 Pub/Sub 라이트 위치를 참조하세요.

라이트 주제를 만든 후에는 파티션당 처리량과 스토리지 용량을 확장할 수 있습니다. 파티션 수 또한 늘릴 수 있지만 줄일 수는 없습니다. 자세한 내용은 용량 확장을 참조하세요.

용량 프로비저닝

라이트 주제는 파티션으로 구성됩니다. 파티션은 다음 용량을 지원합니다.

  • 게시 처리량: 메시지를 게시할 수 있는 최대 총 비율입니다.
  • 구독 처리량: 메시지가 라이트 구독으로 전달되는 최대 총 비율입니다.
  • 스토리지: 파티션에 있는 메시지의 최대 총 크기입니다.

스토리지 용량을 초과하면 Pub/Sub 라이트 서비스는 게시에 실패하는 경우가 없습니다. 대신 가장 오래된 메시지의 메시지 보관 기간과 관계없이 파티션에서 가장 오래된 메시지를 삭제합니다. Pub/Sub 라이트 서비스는 최상의 방식으로 메시지를 삭제합니다.

용량 가격에 대한 자세한 내용은 Pub/Sub 라이트 가격 책정을 참조하세요.

라이트 주제 업데이트

메시지 보관 기간을 업데이트하고 라이트 주제의 용량을 확장할 수 있습니다. 주제의 영역을 업데이트할 수 없습니다. 라이트 주제의 용량을 확장하려면 확장 용량을 참조하세요.

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub Lite API를 사용하여 라이트 주제를 업데이트할 수 있습니다.

Console

  1. Cloud Console에서 라이트 주제 페이지로 이동합니다.

    라이트 주제 페이지로 이동

  2. 라이트 주제 ID를 클릭합니다.

  3. 수정을 클릭합니다.

  4. 파티션 수를 입력합니다. 이는 늘릴 수 있지만 줄일 수는 없습니다.

  5. 파티션당 스토리지보관 기간을 입력합니다.

  6. 게시 처리량을 선택합니다.

  7. 구독 처리량을 선택합니다.

  8. 파티션당 스토리지를 입력합니다.

gcloud

라이트 주제를 업데이트하려면 gcloud pubsub lite-topics update 명령어를 사용합니다.

gcloud pubsub lite-topics update TOPIC_ID \
  --zone=ZONE \
  --partitions=NUMBER_OF_PARTITIONS \
  --per-partition-publish-mib=PUBLISHING_CAPACITY \
  --per-partition-subscribe-mib=SUBSCRIBING_CAPACITY \
  --per-partition-bytes=STORAGE_PER_PARTITION \
  --message-retention-period=MESSAGE_RETENTION_PERIOD

다음을 바꿉니다.

  • TOPIC_ID: 라이트 주제의 ID

  • ZONE: 라이트 주제가 있는 영역의 이름

  • NUMBER_OF_PARTITIONS: 라이트 주제를 위해 구성할 파티션 수

  • PUBLISHING_CAPACITY: 각 파티션의 게시 처리량 용량(정수)

  • SUBSCRIBING_CAPACITY: 각 파티션의 구독 처리량 용량(정수)

  • STORAGE_PER_PARTITION: 각 파티션의 스토리지 용량(예: 30GiB)

  • MESSAGE_RETENTION_PERIOD: 라이트 주제에서 메시지를 저장하는 시간(예: 1d 또는 2w)

요청이 성공하면 명령줄에 라이트 주제가 표시됩니다.

name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOD

프로토콜

라이트 주제를 업데이트하려면 다음과 같이 PATCH 요청을 보내세요.

PATCH https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID?updateMask=partitionConfig.capacity,retentionConfig.perPartitionBytes,retentionConfig.period,partitionConfig.count
Authorization: Bearer $(gcloud auth print-access-token)

다음을 바꿉니다.

  • REGION: 라이트 주제가 있는 영역의 리전

  • PROJECT_NUMBER: 라이트 주제가 있는 프로젝트의 프로젝트 번호

  • ZONE: 라이트 주제가 있는 영역의 이름

  • TOPIC_ID: 라이트 주제의 ID

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

{
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

다음을 바꿉니다.

  • PUBLISHING_CAPACITY: 각 파티션의 게시 처리량 용량(정수)

  • SUBSCRIBING_CAPACITY: 각 파티션의 구독 처리량 용량(정수)

  • STORAGE_PER_PARTITION: 각 파티션의 스토리지 용량(예: 30GiB)

  • MESSAGE_RETENTION_PERIOD: 라이트 주제에서 메시지를 저장하는 시간(예: 1d 또는 2w)

  • NUMBER_OF_PARTITIONS: 라이트 주제를 위해 구성할 파티션 수

요청이 성공하는 경우 응답은 JSON 형식의 라이트 주제입니다.

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

Go

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참조 문서를 참조하세요.

import (
	"context"
	"fmt"
	"io"
	"time"

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

func updateTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	topicPath := fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID)
	// For ranges of fields in TopicConfigToUpdate, see https://pkg.go.dev/cloud.google.com/go/pubsublite/#TopicConfigToUpdate
	config := pubsublite.TopicConfigToUpdate{
		Name:                       topicPath,
		PartitionCount:             3, // Partition count cannot decrease.
		PublishCapacityMiBPerSec:   8,
		SubscribeCapacityMiBPerSec: 16,
		PerPartitionBytes:          60 * 1024 * 1024 * 1024,
		RetentionDuration:          24 * time.Hour,
	}
	updatedCfg, err := client.UpdateTopic(ctx, config)
	if err != nil {
		return fmt.Errorf("client.UpdateTopic got err: %v", err)
	}
	fmt.Fprintf(w, "Updated topic: %#v\n", *updatedCfg)
	return nil
}

자바

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

import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;
import com.google.cloud.pubsublite.proto.Topic.PartitionConfig;
import com.google.cloud.pubsublite.proto.Topic.RetentionConfig;
import com.google.protobuf.FieldMask;
import com.google.protobuf.util.Durations;
import java.util.Arrays;

public class UpdateTopicExample {

  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";
    long projectNumber = Long.parseLong("123456789");

    updateTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void updateTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {

    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    Iterable<String> iterablePaths =
        Arrays.asList(
            "partition_config.scale",
            "retention_config.per_partition_bytes",
            "retention_config.period");

    FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(iterablePaths).build();

    Topic topic =
        Topic.newBuilder()
            .setPartitionConfig(
                PartitionConfig.newBuilder()
                    // Set publishing throughput to 4 times the standard partition
                    // throughput of 4 MiB per sec. This must be in the range [1,4]. A
                    // topic with `scale` of 2 and count of 10 is charged for 20 partitions.
                    .setScale(4)
                    .build())
            .setRetentionConfig(
                RetentionConfig.newBuilder()
                    // Set storage per partition to 200 GiB. This must be 30 GiB-10 TiB.
                    // If the number of bytes stored in any of the topic's partitions grows
                    // beyond this value, older messages will be dropped to make room for
                    // newer ones, regardless of the value of `period`.
                    // Be careful when decreasing storage per partition as it may cause
                    // lost messages.
                    .setPerPartitionBytes(200 * 1024 * 1024 * 1024L)
                    .setPeriod(Durations.fromDays(7)))
            .setName(topicPath.toString())
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic topicBeforeUpdate = adminClient.getTopic(topicPath).get();
      System.out.println("Before update: " + topicBeforeUpdate.getAllFields());

      Topic topicAfterUpdate = adminClient.updateTopic(topic, fieldMask).get();
      System.out.println("After update: " + topicAfterUpdate.getAllFields());
    }
  }
}

Python

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

from google.api_core.exceptions import NotFound
from google.cloud.pubsublite import AdminClient, Topic
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath
from google.protobuf.duration_pb2 import Duration
from google.protobuf.field_mask_pb2 import FieldMask

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

# Defines which topic fields to update.
field_mask = FieldMask(
    paths=[
        "partition_config.scale",
        "retention_config.per_partition_bytes",
        "retention_config.period",
    ]
)

# Defines how to update the topic fields.
topic = Topic(
    name=str(topic_path),
    partition_config=Topic.PartitionConfig(
        # Set publishing throughput to 2x standard partition throughput of 4 MiB
        # per second. This must in the range [1,4]. A topic with `scale` of 2 and
        # `count` of 10 is charged for 20 partitions.
        scale=2,
    ),
    retention_config=Topic.RetentionConfig(
        # Set storage per partition to 100 GiB. This must be in the range 30 GiB-10TiB.
        # If the number of byptes stored in any of the topic's partitions grows beyond
        # this value, older messages will be dropped to make room for newer ones,
        # regardless of the value of `period`.
        # Be careful when decreasing storage per partition as it may cuase lost messages.
        per_partition_bytes=100 * 1024 * 1024 * 1024,
        # Allow messages to be stored for 14 days.
        period=Duration(seconds=60 * 60 * 24 * 14),
    ),
)

client = AdminClient(cloud_region)
try:
    response = client.update_topic(topic, field_mask)
    print(f"{response.name} updated successfully.")
except NotFound:
    print(f"{topic_path} not found.")

처리량 용량 확장

주제의 처리량 용량을 수직 및 수평으로 확장할 수 있습니다. 수직 확장에는 주제 파티션의 크기를 늘리거나 줄이는 작업이 포함됩니다. Pub/Sub 라이트 서비스는 라이트 주제의 각 파티션에 동일한 양의 처리량 용량을 프로비저닝합니다. 예를 들어 게시 처리량 용량을 초당 10 MiB로늘리면 각 파티션은 초당 10 MiB의 게시 처리량을 얻게 됩니다.

또한 파티션 수를 늘려 라이트 주제의 용량을 수평으로 늘릴 수도 있습니다. 주제의 파티션 수를 줄일 수 없습니다.

파티션 수를 변경해도 메시지의 상대적 순서는 유지되지 않습니다. 주제의 파티션 수를 업데이트하면 순서 키에서 파티션으로 매핑하는 데 사용되는 해시 함수가 변경됩니다. 파티션 수 업데이트 후 게시된 동일한 키를 가진 메시지는 업데이트 전에 게시된 것과 다른 파티션에 매핑될 수 있습니다. 또한 주제 크기 조절이 모든 게시자에게 전파되는 데 시간이 걸릴 수 있으므로 잠시 동안 일부 게시자는 새로운 해시 함수를 사용하고 일부는 여전히 오래된 해시 함수를 사용할 수 있습니다.

스토리지 용량 확장

라이트 주제에서 스토리지 용량을 늘리거나 줄일 수도 있습니다. 라이트 주제는 각 파티션에 동일한 양의 스토리지를 프로비저닝합니다. 스토리지를 60 GiB로 늘리면 각 파티션은 60 GiB의 스토리지를 얻게 됩니다.

라이트 주제의 스토리지 용량을 줄이면 Pub/Sub 라이트 서비스가 가장 오래된 메시지를 먼저 삭제합니다.

용량 가격에 대한 자세한 내용은 Pub/Sub 라이트 가격 책정을 참조하세요.

라이트 주제 세부정보 가져오기

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub Lite API를 사용하여 라이트 주제에 대한 세부정보를 가져올 수 있습니다.

Console

  1. Cloud Console에서 라이트 주제 페이지로 이동합니다.

    라이트 주제 페이지로 이동

  2. 라이트 주제 ID를 클릭합니다.

gcloud

라이트 주제에 대한 세부정보를 가져오려면 gcloud pubsub lite-topics describe 명령어를 사용합니다.

gcloud pubsub lite-topics describe TOPIC_ID \
--zone=ZONE

다음을 바꿉니다.

  • TOPIC_ID: 라이트 주제의 ID

  • ZONE: 라이트 주제가 있는 영역의 이름

요청이 성공하면 명령줄에 라이트 주제가 표시됩니다.

name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOD

프로토콜

라이트 주제에 대한 세부정보를 가져오려면 다음과 같이 GET 요청을 보냅니다.

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
Authorization: Bearer $(gcloud auth print-access-token)

다음을 바꿉니다.

  • REGION: 라이트 주제가 있는 영역의 리전

  • PROJECT_NUMBER: 라이트 주제가 있는 프로젝트의 프로젝트 번호

  • ZONE: 라이트 주제가 있는 영역의 이름

  • TOPIC_ID: 라이트 주제의 ID

요청이 성공하는 경우 응답은 JSON 형식의 라이트 주제입니다.

{
  "name": projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID,
  "partitionConfig": {
      "count": NUMBER_OF_PARTITIONS,
      "capacity": {
         "publishMibPerSec": PUBLISHING_CAPACITY,
         "subscribeMibPerSec": SUBSCRIBING_CAPACITY,
      }
   },
   "retentionConfig": {
       "perPartitionBytes": STORAGE_PER_PARTITION,
       "period": MESSAGE_RETENTION_PERIOD,
   },
}

Go

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참조 문서를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

func getTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	topicName := fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID)
	topic, err := client.Topic(ctx, topicName)
	if err != nil {
		return fmt.Errorf("client.Topic got err: %v", err)
	}
	fmt.Fprintf(w, "Got topic: %#v\n", *topic)
	return nil
}

자바

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

import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;
import com.google.cloud.pubsublite.proto.Topic;

public class GetTopicExample {

  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';
    // Choose an existing topic.
    String topicId = "your-topic-id";
    long projectNumber = Long.parseLong("123456789");

    getTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void getTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {
    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      Topic topic = adminClient.getTopic(topicPath).get();
      long numPartitions = adminClient.getTopicPartitionCount(topicPath).get();
      System.out.println(topic.getAllFields() + "\nhas " + numPartitions + " partition(s).");
    }
  }
}

Python

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

from google.api_core.exceptions import NotFound
from google.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

client = AdminClient(cloud_region)
try:
    response = client.get_topic(topic_path)
    num_partitions = client.get_topic_partition_count(topic_path)
    print(f"{response.name} has {num_partitions} partition(s).")
except NotFound:
    print(f"{topic_path} not found.")

라이트 주제 나열

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub Lite API를 사용하여 프로젝트의 라이트 주제를 나열할 수 있습니다.

Console

프로젝트의 라이트 주제 목록을 보려면 라이트 주제 페이지로 이동하세요.

gcloud

프로젝트의 라이트 주제를 나열하려면 gcloud pubsub lite-topics list 명령어를 사용합니다.

gcloud pubsub lite-topics list \
  --zone=ZONE

ZONE을 라이트 주제가 있는 영역의 이름으로 바꿉니다.

요청이 성공하면 명령줄에 라이트 주제가 표시됩니다.

---
name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOND
---
name: projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
partitionConfig:
  count: NUMBER_OF_PARTITIONS
  capacity:
    publishMibPerSec: PUBLISHING_CAPACITY
    subscribeMibPerSec: SUBSCRIBING_CAPACITY
retentionConfig:
  perPartitionBytes: STORAGE_PER_PARTITION
  period: MESSAGE_RETENTION_PERIOND

프로토콜

프로젝트의 라이트 주제를 나열하려면 다음과 같이 GET 요청을 보냅니다.

GET https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/topics
Authorization: Bearer $(gcloud auth print-access-token)

다음을 바꿉니다.

  • REGION: 라이트 주제가 있는 영역의 리전

  • PROJECT_NUMBER: 라이트 주제가 있는 프로젝트의 프로젝트 번호

요청이 성공하는 경우 응답은 JSON 형식의 라이트 주제 목록입니다.

{
  "topics": [
      {
          "name": "projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID",
      },
      {
          "name": "projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID",
      }
  ]
}

Go

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참조 문서를 참조하세요.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsublite"
	"google.golang.org/api/iterator"
)

func listTopics(w io.Writer, projectID, region, zone string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	parent := fmt.Sprintf("projects/%s/locations/%s", projectID, zone)
	topicIter := client.Topics(ctx, parent)
	for {
		topic, err := topicIter.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return fmt.Errorf("topicIter.Next got err: %v", err)
		}
		fmt.Fprintf(w, "Got topic: %#v\n", topic)
	}
	return nil
}

자바

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

import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.LocationPath;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.proto.Topic;
import java.util.List;

public class ListTopicsExample {

  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';
    long projectNumber = Long.parseLong("123456789");

    listTopicsExample(cloudRegion, zoneId, projectNumber);
  }

  public static void listTopicsExample(String cloudRegion, char zoneId, long projectNumber)
      throws Exception {

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    LocationPath locationPath =
        LocationPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      List<Topic> topics = adminClient.listTopics(locationPath).get();
      for (Topic topic : topics) {
        System.out.println(topic.getAllFields());
      }
      System.out.println(topics.size() + " topic(s) listed.");
    }
  }
}

Python

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

from google.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, LocationPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
location_path = LocationPath(project_number, location)

client = AdminClient(cloud_region)
response = client.list_topics(location_path)

for topic in response:
    print(topic)

print(f"{len(response)} topic(s) listed in your project and location.")

라이트 주제 삭제

Cloud Console, gcloud 명령줄 도구 또는 Pub/Sub Lite API를 사용하여 라이트 주제를 삭제할 수 있습니다.

Console

  1. Cloud Console에서 라이트 주제 페이지로 이동합니다.

    라이트 주제 페이지로 이동

  2. 라이트 주제 ID를 클릭합니다.

  3. 주제 세부정보 페이지에서 삭제를 클릭합니다.

  4. 표시되는 필드에 delete를 입력하여 라이트 주제를 삭제할지 여부를 확인합니다.

  5. 삭제를 클릭합니다.

gcloud

라이트 주제를 삭제하려면 gcloud pubsub lite-topics delete 명령어를 사용합니다.

  1. delete 명령어를 실행합니다.

    gcloud pubsub lite-topics delete TOPIC_ID \
     --zone=ZONE
    

    다음을 바꿉니다.

    • TOPIC_ID: 라이트 주제의 ID

    • ZONE: 라이트 주제가 있는 영역의 이름

  2. 확인하려면 Y를 입력합니다.

요청이 성공하면 응답은 다음과 같습니다.

Deleted topic [TOPIC_ID].

프로토콜

라이트 주제를 삭제하려면 다음과 같이 DELETE 요청을 보냅니다.

DELETE https://REGION-pubsublite.googleapis.com/v1/admin/projects/PROJECT_NUMBER/locations/ZONE/topics/TOPIC_ID
Authorization: Bearer $(gcloud auth print-access-token)

다음을 바꿉니다.

  • REGION: 라이트 주제가 있는 영역의 리전

  • PROJECT_NUMBER: 라이트 주제가 있는 프로젝트의 프로젝트 번호

  • ZONE: 라이트 주제가 있는 영역의 이름

  • TOPIC_ID: 라이트 주제의 ID

요청이 성공하면 응답은 빈 JSON 객체입니다.

Go

이 샘플을 시도하기 전에 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참조 문서를 참조하세요.

import (
	"context"
	"fmt"
	"io"

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

func deleteTopic(w io.Writer, projectID, region, zone, topicID string) error {
	// projectID := "my-project-id"
	// region := "us-central1"
	// zone := "us-central1-a"
	// topicID := "my-topic"
	ctx := context.Background()
	client, err := pubsublite.NewAdminClient(ctx, region)
	if err != nil {
		return fmt.Errorf("pubsublite.NewAdminClient: %v", err)
	}
	defer client.Close()

	err = client.DeleteTopic(ctx, fmt.Sprintf("projects/%s/locations/%s/topics/%s", projectID, zone, topicID))
	if err != nil {
		return fmt.Errorf("client.DeleteTopic got err: %v", err)
	}
	fmt.Fprint(w, "Deleted topic\n")
	return nil
}

자바

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

import com.google.cloud.pubsublite.AdminClient;
import com.google.cloud.pubsublite.AdminClientSettings;
import com.google.cloud.pubsublite.CloudRegion;
import com.google.cloud.pubsublite.CloudZone;
import com.google.cloud.pubsublite.ProjectNumber;
import com.google.cloud.pubsublite.TopicName;
import com.google.cloud.pubsublite.TopicPath;

public class DeleteTopicExample {

  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';
    // Choose an existing topic.
    String topicId = "your-topic-id";
    long projectNumber = Long.parseLong("123456789");

    deleteTopicExample(cloudRegion, zoneId, projectNumber, topicId);
  }

  public static void deleteTopicExample(
      String cloudRegion, char zoneId, long projectNumber, String topicId) throws Exception {
    TopicPath topicPath =
        TopicPath.newBuilder()
            .setProject(ProjectNumber.of(projectNumber))
            .setLocation(CloudZone.of(CloudRegion.of(cloudRegion), zoneId))
            .setName(TopicName.of(topicId))
            .build();

    AdminClientSettings adminClientSettings =
        AdminClientSettings.newBuilder().setRegion(CloudRegion.of(cloudRegion)).build();

    try (AdminClient adminClient = AdminClient.create(adminClientSettings)) {
      adminClient.deleteTopic(topicPath).get();
      System.out.println(topicPath.toString() + " deleted successfully.");
    }
  }

Python

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

from google.api_core.exceptions import NotFound
from google.cloud.pubsublite import AdminClient
from google.cloud.pubsublite.types import CloudRegion, CloudZone, TopicPath

# TODO(developer):
# project_number = 1122334455
# cloud_region = "us-central1"
# zone_id = "a"
# topic_id = "your-topic-id"

cloud_region = CloudRegion(cloud_region)
location = CloudZone(cloud_region, zone_id)
topic_path = TopicPath(project_number, location, topic_id)

client = AdminClient(cloud_region)
try:
    client.delete_topic(topic_path)
    print(f"{topic_path} deleted successfully.")
except NotFound:
    print(f"{topic_path} not found.")

라이트 주제를 삭제하면 라이트 주제에 메시지를 게시할 수 없습니다. 라이트 주제에 대한 라이트 구독이 여전히 존재하지만 라이트 구독에서 메시지를 받을 수 없습니다.