Cloud Storage 구독 만들기

이 문서에서는 Cloud Storage 구독을 만드는 방법을 설명합니다. Google Cloud 콘솔, Google Cloud CLI, 클라이언트 라이브러리, Pub/Sub API를 사용하여 Cloud Storage 구독을 만들 수 있습니다.

시작하기 전에

이 문서를 읽기 전 다음 내용을 숙지해야 합니다.

• Cloud Storage 구독의 작동 방식
• Cloud Storage의 작동 방식과 Cloud Storage 버킷을 만들고 관리하는 방법
• 메시지 오류 처리를 위해 데드 레터 주제를 구성하는 방법

필수 역할 및 권한

다음은 역할 및 권한과 관련된 가이드라인 목록입니다.

• 구독을 만들려면 프로젝트 수준에서 액세스 제어를 구성해야 합니다.

• 또한 이 섹션의 뒷부분에서 설명하는 것처럼 구독과 주제가 다른 프로젝트에 있는 경우 리소스 수준 권한도 필요합니다.

• Cloud Storage 구독을 만들려면 Pub/Sub 서비스 계정에 특정 Cloud Storage 버킷에 쓰기 권한과 버킷 메타데이터 읽기 권한이 있어야 합니다. 이러한 권한을 부여하는 방법에 대한 자세한 내용은 이 문서의 다음 섹션을 참조하세요.

Cloud Storage 구독을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Pub/Sub 편집자(roles/pubsub.editor) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 Cloud Storage 구독을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.

한 프로젝트에서 다른 프로젝트의 주제와 연결된 Cloud Storage 구독을 만들어야 하는 경우 주제 관리자에게 주제에 대한 Pub/Sub 편집자 (roles/pubsub.editor) IAM 역할도 부여해 달라고 요청하세요.

Pub/Sub 서비스 계정에 Cloud Storage 역할 할당

일부 Google Cloud 서비스에는 서비스가 리소스에 액세스하도록 허용하는 Google Cloud 관리형 서비스 계정이 있습니다. 이러한 서비스 계정을 서비스 에이전트라고도 합니다. Pub/Sub는 service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com 형식으로 각 프로젝트에 대해 서비스 계정을 만들고 유지합니다.

Cloud Storage 구독을 만들려면 Pub/Sub 서비스 계정에 특정 Cloud Storage 버킷에 쓰기 권한과 버킷 메타데이터 읽기 권한이 있어야 합니다. 다음 절차 중 하나를 선택하세요.

• 버킷 수준에서 권한을 부여합니다. 특정 Cloud Storage 버킷에서 스토리지 객체 생성자(roles/storage.objectCreator) 역할과 스토리지 기존 버킷 리더(roles/storage.legacyBucketReader) 역할을 Pub/Sub 서비스 계정에 부여합니다.

• 프로젝트 수준에서 역할을 부여해야 하는 경우 대신 Cloud Storage 버킷이 포함된 프로젝트에 대한 스토리지 관리자(roles/storage.admin) 역할을 부여할 수 있습니다. Pub/Sub 서비스 계정에 이 역할을 부여합니다.

Cloud Storage IAM에 관한 자세한 내용은 Cloud Storage ID 및 액세스 관리를 참고하세요.

Cloud Storage 구독 속성

Cloud Storage 구독을 구성할 때는 모든 구독 유형에 공통적인 속성과 일부 추가 Cloud Storage 구독별 속성을 지정해야 합니다.

일반 구독 속성

모든 구독에 설정할 수 있는 일반적인 구독 속성에 대해 알아봅니다.

버킷 이름

Cloud Storage 구독을 만들기 전에 Cloud Storage 버킷이 이미 있어야 합니다.

메시지는 일괄적으로 전송되고 Cloud Storage 버킷에 저장됩니다. 단일 배치 또는 파일은 버킷에 객체로 저장됩니다.

Cloud Storage 버킷에 요청자 지불이 중지되어 있어야 합니다.

Cloud Storage 버킷을 만들려면 버킷 만들기를 참조하세요.

파일 이름 접두어, 접미사, 날짜 시간

Cloud Storage 구독에서 생성된 출력 Cloud Storage 파일은 Cloud Storage 버킷에 객체로 저장됩니다. Cloud Storage 버킷에 저장된 객체의 이름은 <file-prefix><UTC-date-time>_<uuid><file-suffix> 형식입니다.

다음 목록에는 파일 형식 및 맞춤설정할 수 있는 필드에 관한 세부정보가 포함되어 있습니다.

• <file-prefix>는 커스텀 파일 이름 프리픽스입니다. 이 필드는 선택 사항입니다.

• <UTC-date-time>은 객체가 생성된 시간을 기반으로 맞춤설정 가능한 자동 생성 문자열입니다.

• <uuid>은 객체의 자동 생성 무작위 문자열입니다.

• <file-suffix>는 커스텀 파일 이름 접미사입니다. 이 필드는 선택 사항입니다. 파일 이름 서픽스는 '/'로 끝날 수 없습니다.

• 파일 이름 접두사와 접미사를 변경할 수 있습니다.

  • 예를 들어 파일 이름 프리픽스 값이 prod_이고 파일 이름 서픽스가 _archive이면 샘플 객체 이름은 prod_2023-09-25T04:10:00+00:00_uN1QuE_archive입니다.

  • 파일 이름 프리픽스와 서픽스를 지정하지 않으면 Cloud Storage 버킷에 저장된 객체 이름은 <UTC-date-time>_<uuid> 형식입니다.

  • Cloud Storage 객체 이름 지정 요구사항은 파일 이름 프리픽스 및 서픽스에도 적용됩니다. 자세한 내용은 Cloud Storage 객체 정보를 참조하세요.

• 파일 이름에 날짜와 시간이 표시되는 방식을 변경할 수 있습니다.

  • 한 번만 사용할 수 있는 필수 날짜/시간 일치자에는 년(YYYY 또는 YY), 월(MM), 일(DD), 시간(hh), 분(mm), 초(ss) 등이 있습니다. 예를 들어 YY-YYYY 또는 MMM은 유효하지 않습니다.

  • 한 번만 사용할 수 있는 선택적 일치자에는 날짜/시간 구분자(T) 및 시간대 오프셋(Z 또는 +00:00) 등이 있습니다.

  • 여러 번 사용할 수 있는 선택적 요소: 하이픈(-), 밑줄(_), 콜론(:), 슬래시(/)가 있습니다.

  • 예를 들어 파일 이름 날짜/시간 형식의 값이 YYYY-MM-DD/hh_mm_ssZ이면 샘플 객체 이름은 prod_2023-09-25/04_10_00Z_uNiQuE_archive입니다.

  • 파일 이름 날짜/시간 형식이 일치자가 아닌 문자로 끝나는 경우, 해당 문자는 <UTC-date-time>과 <uuid> 사이의 구분자를 대체합니다. 예를 들어 파일 이름 날짜/시간 형식의 값이 YYYY-MM-DDThh_mm_ss-이면 샘플 객체 이름은 prod_2023-09-25T04_10_00-uNiQuE_archive입니다.

파일 일괄 처리

Cloud Storage 구독을 사용하면 Cloud Storage 버킷에 객체로 저장되는 새 출력 파일을 만들 시점을 결정할 수 있습니다. Pub/Sub는 지정된 일괄 처리 조건 중 하나가 충족되면 출력 파일을 씁니다. Cloud Storage 일괄 처리 조건은 다음과 같습니다.

• 스토리지 일괄 최대 기간. 필수 설정입니다. Cloud Storage 구독은 지정된 최대 기간 값을 초과하면 새 출력 파일을 작성합니다. 값을 지정하지 않으면 기본값 5분이 적용됩니다. 최대 기간에 적용되는 값은 다음과 같습니다.

  • 최솟값 = 1분
  • 기본값 = 5분
  • 최댓값 = 10분

• 스토리지 일괄 최대 바이트. 이 설정은 선택사항입니다. Cloud Storage 구독은 지정된 최대 바이트 값을 초과하면 새 출력 파일을 작성합니다. 최대 바이트에 적용 가능한 값은 다음과 같습니다.

  • 최솟값 = 1KB
  • 최댓값 = 10GiB

• 스토리지 일괄 최대 메시지. 이 설정은 선택사항입니다. Cloud Storage 구독은 지정된 최대 메시지 수가 초과되면 새 출력 파일을 작성합니다. 적용 가능한 최대 메시지 값은 다음과 같습니다.

  • 최솟값 = 1000

예를 들어 최대 기간을 6분으로, 최대 바이트를 2GB로 구성할 수 있습니다. 4분 후 출력 파일이 2GB의 파일 크기에 도달하면 Pub/Sub는 이전 파일을 마무리하고 새 파일에 쓰기를 시작합니다.

Cloud Storage 구독은 Cloud Storage 버킷의 여러 파일에 동시에 쓸 수 있습니다. 6분마다 새 파일을 만들도록 구독을 구성한 경우 6분마다 여러 Cloud Storage 파일이 생성되는 것을 확인할 수 있습니다.

경우에 따라 Pub/Sub가 파일 일괄 처리 조건에서 구성된 시간보다 일찍 새 파일에 쓰기를 시작할 수 있습니다. 구독이 최대 바이트 값보다 큰 메시지를 수신하는 경우 파일이 최대 바이트 값을 초과할 수도 있습니다.

파일 형식

Cloud Storage 구독을 만들 때 Cloud Storage 버킷에 저장할 출력 파일의 형식을 텍스트 또는 Avro로 지정할 수 있습니다.

• 텍스트: 메시지는 일반 텍스트로 저장됩니다. 줄바꿈 문자는 파일의 이전 메시지와 메시지를 분리합니다. 메시지 페이로드만 저장되며 속성 또는 기타 메타데이터가 저장되지 않습니다.

• Avro: 메시지는 Apache Avro 바이너리 형식으로 저장됩니다. Avro를 선택하면 다음과 같은 추가 속성을 사용 설정할 수 있습니다.

  • 메타데이터 쓰기: 이 옵션을 사용하면 메시지와 함께 메시지 메타데이터를 저장할 수 있습니다. subscription_name, message_id, publish_time과 같은 메타데이터 및 attributes 필드가 출력 Avro 객체의 최상위 필드에 작성되는 반면 데이터 이외의 다른 모든 메시지 속성(예: ordering_key(있는 경우))은 attributes 맵에 항목으로 추가됩니다.

    메타데이터 쓰기가 사용 중지된 경우 메시지 페이로드만 출력 Avro 객체에 기록됩니다. 다음은 쓰기 메타데이터가 사용 중지된 출력 메시지의 Avro 스키마입니다.

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessage",
      "fields": [
        { "name": "data", "type": "bytes" }
      ]
    }
    

    다음은 쓰기 메타데이터가 사용 설정된 출력 메시지의 Avro 스키마입니다.

    {
      "type": "record",
      "namespace": "com.google.pubsub",
      "name": "PubsubMessageWithMetadata",
      "fields": [
        { "name": "subscription_name", "type": "string" },
        { "name": "message_id", "type": "string"  },
        { "name": "publish_time", "type": {
            "type": "long",
            "logicalType": "timestamp-micros"
          }
        },
        { "name": "attributes", "type": { "type": "map", "values": "string" } },
        { "name": "data", "type": "bytes" }
      ]
    }
    

  • 주제 스키마 사용: 이 옵션을 사용하면 Pub/Sub가 Avro 파일을 쓸 때 구독이 연결된 Pub/Sub 주제의 스키마를 사용할 수 있습니다.

    이 옵션을 사용할 때는 다음 추가 요구사항을 확인해야 합니다.

    • 주제 스키마는 Apache Avro 형식이어야 합니다.

    • 주제 스키마 사용 및 메타데이터 쓰기가 모두 사용 설정된 경우 주제 스키마의 루트에 레코드 객체가 있어야 합니다. Pub/Sub은 레코드의 필드 목록을 확장하여 메타데이터 필드를 포함합니다. 따라서 레코드에 메타데이터 필드(subscription_name, message_id, publish_time 또는 attributes)와 동일한 이름의 필드가 포함될 수 없습니다.

Cloud Storage 구독 만들기

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, std::string const& bucket) {
  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.mutable_cloud_storage_config()->set_bucket(bucket);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

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

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

// createCloudStorageSubscription creates a Pub/Sub subscription that exports messages to Cloud Storage.
func createCloudStorageSubscription(w io.Writer, projectID, subID string, topic *pubsub.Topic, bucket string) error {
	// projectID := "my-project-id"
	// subID := "my-sub"
	// topic of type https://godoc.org/cloud.google.com/go/pubsub#Topic
	// note bucket should not have the gs:// prefix
	// bucket := "my-bucket"
	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,
		CloudStorageConfig: pubsub.CloudStorageConfig{
			Bucket:         bucket,
			FilenamePrefix: "log_events_",
			FilenameSuffix: ".avro",
			OutputFormat:   &pubsub.CloudStorageOutputFormatAvroConfig{WriteMetadata: true},
			MaxDuration:    1 * time.Minute,
			MaxBytes:       1e8,
		},
	})
	if err != nil {
		return fmt.Errorf("client.CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created Cloud Storage subscription: %v\n", sub)

	return nil
}

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

public class CreateCloudStorageSubscriptionExample {
  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";
    String bucket = "your-bucket";
    String filenamePrefix = "log_events_";
    String filenameSuffix = ".text";
    Duration maxDuration = Duration.newBuilder().setSeconds(300).build();

    createCloudStorageSubscription(
        projectId, topicId, subscriptionId, bucket, filenamePrefix, filenameSuffix, maxDuration);
  }

  public static void createCloudStorageSubscription(
      String projectId,
      String topicId,
      String subscriptionId,
      String bucket,
      String filenamePrefix,
      String filenameSuffix,
      Duration maxDuration)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

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

      CloudStorageConfig cloudStorageConfig =
          CloudStorageConfig.newBuilder()
              .setBucket(bucket)
              .setFilenamePrefix(filenamePrefix)
              .setFilenameSuffix(filenameSuffix)
              .setMaxDuration(maxDuration)
              .build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setCloudStorageConfig(cloudStorageConfig)
                  .build());

      System.out.println("Created a CloudStorage subscription: " + subscription.getAllFields());
    }
  }
}

Cloud Storage 구독 모니터링

Cloud Monitoring은 구독을 모니터링하기 위한 여러 측정항목을 제공합니다.

Pub/Sub와 관련하여 사용 가능한 모든 측정항목 및 설명 목록은 Pub/Sub 모니터링 문서를 참조하세요.

Pub/Sub 내에서도 구독을 모니터링할 수 있습니다.

다음 단계

• Cloud Storage 구독 문제 해결

• Cloud Storage에 대해 알아보기

• Cloud Storage 구독을 포함한 Pub/Sub의 가격 검토