이 문서에서는 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 구독을 만들려면 다음 권한이 필요합니다.
-
구독 만들기:
pubsub.subscriptions.create
-
주제에 구독 연결하기:
pubsub.topics.attachSubscription
-
구독에서 가져오기:
pubsub.subscriptions.consume
-
구독 가져오기:
pubsub.subscriptions.get
-
구독 나열:
pubsub.subscriptions.list
-
구독 업데이트:
pubsub.subscriptions.update
-
구독 삭제:
pubsub.subscriptions.delete
-
구독의 IAM 정책 가져오기:
pubsub.subscriptions.getIamPolicy
-
구독의 IAM 정책 구성:
pubsub.subscriptions.setIamPolicy
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
한 프로젝트에서 다른 프로젝트의 주제와 연결된 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 서비스 계정에 이 역할을 부여합니다.
버킷 권한
다음 단계에 따라 버킷 수준에서 스토리지 객체 생성자(roles/storage.objectCreator
) 및 스토리지 기존 버킷 리더(roles/storage.legacyBucketReader
) 역할을 부여합니다.
Google Cloud 콘솔에서 Cloud Storage 페이지로 이동합니다.
메시지를 작성할 Cloud Storage 버킷을 클릭합니다.
버킷 세부정보 페이지가 열립니다.
버킷 세부정보 페이지에서 권한 탭을 클릭합니다.
권한 > 주 구성원별로 보기 탭에서 액세스 권한 부여를 클릭합니다.
액세스 권한 부여 페이지가 열립니다.
주 구성원 추가 섹션에 Pub/Sub 서비스 계정의 이름을 입력합니다.
서비스 계정 형식은
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
입니다. 예를 들어 PROJECT_NUMBER=112233445566
이 있는 프로젝트의 경우 서비스 계정은service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
형식입니다.역할 할당 > 역할 선택 드롭다운에서
Creator
을 입력하고 스토리지 객체 생성자 역할을 선택합니다.다른 역할 추가를 클릭합니다.
역할 선택 드롭다운에서
Bucket Reader
을 입력하고 스토리지 기존 버킷 리더 역할을 선택합니다.저장을 클릭합니다.
프로젝트 권한
프로젝트 수준에서 스토리지 관리자(roles/storage.admin
) 역할을 부여하려면 다음 단계를 따르세요.
Google Cloud 콘솔에서 IAM 페이지로 이동합니다.
권한 > 주 구성원별로 보기 탭에서 액세스 권한 부여를 클릭합니다.
액세스 권한 부여 페이지가 열립니다.
주 구성원 추가 섹션에 Pub/Sub 서비스 계정의 이름을 입력합니다.
서비스 계정 형식은
service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com
입니다. 예를 들어 PROJECT_NUMBER=112233445566
이 있는 프로젝트의 경우 서비스 계정은service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com
형식입니다.역할 할당 > 역할 선택 드롭다운에서
Storage Admin
을 입력하고 스토리지 관리자 역할을 선택합니다.저장을 클릭합니다.
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 구독 만들기
콘솔
-
Google Cloud 콘솔에서 구독 페이지로 이동합니다.
-
구독 만들기를 클릭합니다.
-
구독 ID 필드에 이름을 입력합니다.
구독 이름 지정 방법은 주제 또는 구독 이름 지정 안내를 참조하세요.
-
드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다.
구독은 주제에서 메시지를 수신합니다.
주제를 만드는 방법에 대한 자세한 내용은 주제 만들기 및 관리를 참고하세요.
-
전송 유형을 Cloud Storage에 쓰기로 선택합니다.
-
Cloud Storage 버킷에서 찾아보기를 클릭합니다.
-
적절한 프로젝트에서 기존 버킷을 선택할 수 있습니다.
-
만들기 아이콘을 클릭하고 화면에 표시된 안내에 따라 새 버킷을 만들 수도 있습니다.
버킷을 만든 후 Cloud Storage 구독의 버킷을 선택합니다.
버킷을 만드는 방법에 관한 자세한 내용은 버킷 만들기를 참고하세요.
버킷을 지정하면 Pub/Sub에서 Pub/Sub 서비스 계정의 버킷에 적절한 권한이 있는지 확인합니다. 권한 문제가 있으면
Unable to verify if the Pub/Sub service agent has write permissions on this bucket. You may be lacking permissions to view or set permissions
와 비슷한 메시지가 표시됩니다. -
-
권한 문제가 발생하면 권한 설정을 클릭하고 화면에 표시된 안내를 따릅니다.
또는 Pub/Sub 서비스 계정에 Cloud Storage 역할 할당의 안내를 따르세요.
-
파일 형식으로 텍스트 또는 Avro를 선택합니다.
Avro를 선택하는 경우 원하는 경우 메시지 메타데이터를 출력에 저장할지 여부도 지정할 수 있습니다.
Avro 형식의 메시지 메타데이터 옵션을 비롯한 두 가지 옵션에 관한 자세한 내용은 파일 형식을 참고하세요.
-
선택사항: Cloud Storage 버킷에 기록할 모든 파일에 파일 이름 프리픽스, 서픽스, 날짜/시간을 지정할 수 있습니다. 파일은 버킷에 객체로 저장됩니다.
파일 접두사, 접미사, 날짜 및 시간 설정 방법에 관한 자세한 내용은 파일 이름 접두사, 접미사, 날짜 및 시간을 참고하세요.
-
파일 일괄 처리의 경우 새 파일을 만들기 전에 경과할 최대 시간을 지정합니다.
원하는 경우 파일의 최대 파일 크기나 최대 메시지 수를 설정할 수도 있습니다.
두 파일 일괄 처리 옵션에 대한 자세한 내용은 파일 일괄 처리를 참조하세요.
-
메시지 오류를 처리하려면 데드 레터링을 사용 설정하는 것이 좋습니다.
자세한 내용은 데드 레터 주제를 참고하세요.
-
다른 설정은 기본값으로 두고 만들기를 클릭합니다.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
- Cloud Storage 구독을 만들려면
gcloud pubsub subscriptions create
명령어를 실행합니다.gcloud pubsub subscriptions create SUBSCRIPTION_ID \ --topic=TOPIC_ID \ --cloud-storage-bucket=BUCKET_NAME \ --cloud-storage-file-prefix=CLOUD_STORAGE_FILE_PREFIX \ --cloud-storage-file-suffix=CLOUD_STORAGE_FILE_SUFFIX \ --cloud-storage-file-datetime-format=CLOUD_STORAGE_FILE_DATETIME_FORMAT \ --cloud-storage-max-duration=CLOUD_STORAGE_MAX_DURATION \ --cloud-storage-max-bytes=CLOUD_STORAGE_MAX_BYTES \ --cloud-storage-max-messages=CLOUD_STORAGE_MAX_MESSAGES \ --cloud-storage-output-format=CLOUD_STORAGE_OUTPUT_FORMAT \ --cloud-storage-write-metadata --cloud-storage-use-topic-schema
명령어에서
SUBSCRIPTION_ID
,--topic
플래그,--cloud-storage-bucket
플래그만 필요합니다. 나머지 플래그는 선택사항이며 생략할 수 있습니다.다음을 바꿉니다.
SUBSCRIPTION_ID
: 새 Cloud Storage 구독의 이름 또는 IDTOPIC_ID
: 주제의 이름 또는 IDBUCKET_NAME
: 기존 버킷의 이름을 지정. 예를 들면prod_bucket
입니다. 버킷 이름에 프로젝트 ID를 포함해서는 안 됩니다. 버킷을 만들려면 버킷 만들기를 참조하세요.CLOUD_STORAGE_FILE_PREFIX
: Cloud Storage 파일 이름의 프리픽스를 지정. 예를 들면log_events_
입니다.CLOUD_STORAGE_FILE_SUFFIX
: Cloud Storage 파일 이름의 서픽스를 지정. 예를 들면.txt
입니다.CLOUD_STORAGE_FILE_DATETIME_FORMAT
: Cloud Storage 파일 이름의 날짜 시간 형식을 지정합니다. 예를 들면YYYY-MM-DD/hh_mm_ssZ
입니다.CLOUD_STORAGE_MAX_DURATION
: 새 Cloud Storage 파일이 생성되기 전에 경과할 수 있는 최대 기간. 값은 1m에서 10m 사이여야 합니다. 예를 들면5m
입니다.CLOUD_STORAGE_MAX_BYTES
: 새 파일이 생성되기 전에 Cloud Storage 파일에 기록할 수 있는 최대 바이트. 값은 1KB~10GB 사이여야 합니다. 예를 들면20MB
입니다.CLOUD_STORAGE_MAX_MESSAGES
: 새 파일을 만들기 전에 Cloud Storage 파일에 쓸 수 있는 최대 메시지 수입니다. 값은 1,000 이상이어야 합니다. 예를 들면100000
입니다.CLOUD_STORAGE_OUTPUT_FORMAT
: Cloud Storage에 기록된 데이터의 출력 형식. 값은 다음과 같습니다.text
: 메시지가 줄바꿈으로 구분된 원시 텍스트로 기록됩니다.avro
: 메시지가 Avro 바이너리로 작성됩니다.--cloud-storage-write-metadata
및--cloud-storage-use-topic-schema
는 출력 형식이avro
인 구독에만 영향을 미칩니다.
C++
이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 C++ 설정 안내를 따르세요. 자세한 내용은 Pub/Sub C++ API 참고 문서를 확인하세요.
Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Go
이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Go API 참고 문서를 확인하세요.
Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Java
이 샘플을 사용해 보기 전에 Pub/Sub 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 Pub/Sub Java API 참고 문서를 확인하세요.
Pub/Sub에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Cloud Storage 구독 모니터링
Cloud Monitoring은 구독을 모니터링하기 위한 여러 측정항목을 제공합니다.
Pub/Sub와 관련하여 사용 가능한 모든 측정항목 및 설명 목록은 Pub/Sub 모니터링 문서를 참조하세요.
Pub/Sub 내에서도 구독을 모니터링할 수 있습니다.
다음 단계
Cloud Storage 구독 문제 해결
Cloud Storage에 대해 알아보기
Cloud Storage 구독을 포함한 Pub/Sub의 가격 검토