구독 속성

Pub/Sub 구독 속성은 구독의 특성입니다. 구독을 만들거나 업데이트할 때 구독 속성을 설정할 수 있습니다.

이 문서에서는 구독에 설정할 수 있는 다양한 구독 속성을 설명합니다.

시작하기 전에

구독에 대해 알아보기
만들려는 구독의 워크플로(Pull, Push, BigQuery) 이해하기

일반 구독 속성

구독을 만들 때는 구독 설정을 위한 여러 옵션을 지정해야 합니다. 이러한 속성 중 일부는 모든 유형의 구독에 공통적이며 다음 섹션에서 설명합니다.

메시지 보관 기간

메시지 보관 기간은 Pub/Sub가 게시 후 메시지를 보관하는 기간을 지정합니다. 메시지 보관 기간이 지나면 메시지의 확인 상태에 관계없이 Pub/Sub가 메시지를 삭제할 수 있습니다. 메시지 보관 기간 동안 확인된 메시지를 보관하려면 메시지 다시보기 및 삭제를 참조하세요.

다음은 메시지 보관 기간 옵션의 값입니다.

기본값 = 7일
최솟값 = 10분
최댓값 = 7일

확인되지 않은 메시지는 유휴 구독, 백업 필요, 느린 처리로 인해 발생할 수 있습니다. 24시간 이내에 메시지를 처리할 수 있으면 추가 요금은 발생하지 않습니다. 다음과 같이 이러한 시나리오를 관리하여 새로운 요금이 청구되지 않도록 할 수 있습니다.

유휴 구독. 구독 메시지 보관 요금이 부과되지 않도록 유휴 구독을 삭제합니다.
백업 스토리지. 백업 스토리지로 구독 보관을 사용하는 경우 주제 메시지 보관 또는 확인된 메시지 보관과 같은 다른 스토리지 옵션으로 전환할 수 있습니다. 주제 메시지 보관은 주제 수준에서 메시지를 한 번만 저장하며 필요할 때 모든 구독을 사용할 수 있도록 유지합니다.
처리 지연. 가능한 경우 구독자를 더 추가하여 하루 안에 메시지를 처리합니다.

확인한 메시지 보관

메시지 보관 기간을 지정하면 확인된 메시지를 보관할지 여부도 지정할 수 있습니다.

확인된 메시지 보관 옵션을 사용하면 지정된 메시지 보관 기간 동안 확인된 메시지를 보관할 수 있습니다. 이 옵션을 사용하면 메시지 스토리지 수수료가 증가합니다. 자세한 내용은 스토리지 비용을 참조하세요.

만료 기간

만료 기간 옵션을 사용하면 구독의 만료 기간을 연장할 수 있습니다.

구독자 활동 또는 구독 속성 변경이 없는 구독이 만료됩니다. Pub/Sub에서 구독자 활동이 감지되거나 구독 속성을 업데이트할 경우 구독 삭제 시계가 다시 시작됩니다. 구독자 활동 예시에는 연결 열기, 활성 풀 또는 성공한 push가 있습니다.

만료 기간을 지정하는 경우 값이 메시지 보관 기간 옵션에 지정된 메시지 보관 기간보다 길어야 합니다.

다음은 만료 기간 옵션의 값입니다.

기본값 = 31일
최솟값 = 1일

구독이 만료되지 않게 하려면 만료 기간을 never expire로 설정하세요.

확인 기한

확인 기한 옵션은 확인되지 않은 메시지가 다시 전송되는 초기 기한을 지정합니다. 후속 ModifyAckDeadline 요청을 전송하여 메시지별로 확인 기한을 연장할 수 있습니다.

다음은 확인 기한 옵션의 값입니다.

기본값 = 10초
최솟값 = 10초
최댓값 = 600초

경우에 따라 Pub/Sub 클라이언트 라이브러리에서 전달 속도를 제어하고 확인 기한을 동적으로 수정할 수 있습니다. 이렇게 하면 설정한 확인 기한 전에 메시지가 다시 전송될 수 있습니다. 이 동작을 재정의하려면 minDurationPerAckExtension 및 maxDurationPerAckExtension을 사용합니다. 이러한 값을 사용하는 방법에 대한 자세한 내용은 클라이언트 라이브러리의 1회만 전송 지원을 참조하세요.

구독 필터

구독 필터 옵션을 사용하여 필터링 표현식이 포함된 문자열을 지정하세요. 구독에 필터가 있는 경우 구독은 필터와 일치하는 메시지만 전송합니다. Pub/Sub 서비스는 필터와 일치하지 않는 메시지를 자동으로 확인합니다.

메시지의 데이터가 아닌 속성에 따라 메시지를 필터링할 수 있습니다.
지정하지 않으면 구독은 메시지를 필터링하지 않으며 구독자가 모든 메시지를 수신합니다.
필터를 적용한 후에는 필터를 변경하거나 삭제할 수 없습니다.

필터가 포함된 구독에서 메시지를 받으면 Pub/Sub가 자동으로 확인하는 메시지에 대한 이그레스 요금이 발생하지 않습니다. 이러한 메시지에는 메시지 전송 요금 및 탐색 관련 스토리지 요금이 부과됩니다.

자세한 내용은 구독에서 메시지 필터링을 참조하세요.

메시지 순서

구독에 메시지 순서가 사용 설정되어 있으면 구독자 클라이언트는 동일한 리전에 게시된 메시지를 서비스에서 수신한 순서대로 동일한 순서 키로 수신합니다.

순서가 지정된 전송을 사용하는 경우 이전 메시지에 대한 확인이 처리될 때까지 이후 메시지 확인이 처리되지 않습니다.

게시자는 Pub/Sub가 메시지를 순서대로 전송할 수 있도록 순서 키가 포함된 메시지를 보내야 합니다.

설정하지 않으면 순서 키가 있더라도 Pub/Sub가 메시지를 순서대로 전송하지 못할 수 있습니다.

데드 레터 주제

설정된 전송 횟수 후에 메시지를 전송할 수 없거나 구독자가 메시지를 확인할 수 없는 경우 이러한 메시지를 다시 게시할 수 있는 데드 레터 주제를 구성할 수 있습니다.

데드 레터 주제를 설정한 경우 최대 전송 시도 횟수를 지정할 수도 있습니다. 다음은 데드 레터 주제의 최대 전송 시도 횟수 값입니다.

기본값 = 전송 시도 횟수 5회
최솟값 = 전송 시도 횟수 5회
최댓값 = 전송 시도 100회

데드 레터 주제가 구독과 다른 프로젝트에 있으면 데드 레터 주제와 함께 프로젝트 ID를 지정해야 합니다.

자세한 내용은 데드 레터 주제로 전달을 참조하세요.

재시도 정책

확인 기한이 만료되거나 구독자가 부정 확인으로 응답하는 경우, Pub/Sub가 메시지를 다시 전송할 수 있습니다. 이러한 재전송 시도를 구독 재시도 정책이라고 합니다.

기본적으로 구독의 재시도 정책은 즉시 재시도를 사용하도록 설정됩니다. 이 옵션을 사용하면 확인 기한이 만료되거나 구독자가 부정 확인으로 응답할 때 Pub/Sub가 메시지를 다시 전송합니다.

또한 값을 지수 백오프 지연 후 재시도로 설정할 수도 있습니다. 이 경우 최대 및 최소 백오프 값을 지정해야 합니다.

다음은 최대 및 최소 백오프 값의 값을 설정하는 몇 가지 가이드라인입니다.

백오프 기간의 최댓값을 설정하는 경우 최소 백오프 기간의 기본값은 10초입니다.
백오프 기간의 최솟값을 설정할 경우 최대 백오프 기간의 기본값은 600초입니다.
지정할 수 있는 가장 긴 백오프 기간은 600초입니다.

재시도 정책 및 일괄 메시지

메시지가 배치에 있으면 Pub/Sub는 다음 중 하나가 발생할 때 지수 백오프를 시작합니다.

구독자가 배치에 있는 모든 메시지에 대해 부정 확인을 전송한 경우
확인 기한이 만료된 경우

재시도 정책 및 푸시 구독

push 구독에서 메시지를 받은 경우 Pub/Sub는 지수 백오프 기간 대신 push 백오프 이후에 메시지를 다시 전송할 수 있습니다. push 백오프가 지수 백오프 기간보다 긴 경우, Pub/Sub는 push 백오프 이후에 미확인 메시지를 다시 전송합니다.

pull 구독 속성

pull 구독을 구성할 때 다음 속성을 지정할 수 있습니다.

1회만 전송

1회만 전송. 설정되면 Pub/Sub는 1회만 전송 보장을 이행합니다. 지정하지 않으면 구독은 각 메시지에 최소 1회 전송을 지원합니다.

push 구독 속성

push 구독을 구성할 때 다음 속성을 지정할 수 있습니다.

엔드포인트

엔드포인트 URL(필수) 공개적으로 액세스 가능한 HTTPS 주소입니다. push 엔드포인트의 서버에는 인증 기관에서 서명된 유효한 SSL 인증서가 있어야 합니다. Pub/Sub 서비스는 Pub/Sub 서비스가 메시지를 저장하는 것과 동일한 Google Cloud 리전에서 엔드포인트를 push하는 메시지를 전송합니다. Pub/Sub 서비스는 최선의 방식으로 Google Cloud 리전에서 메시지를 전송합니다.

Pub/Sub에는 push 구독 URL 도메인의 소유권 증명이 더 이상 필요하지 않습니다. 도메인에서 Pub/Sub의 예상치 못한 POST 요청을 받으면 악용 사례로 의심되는 항목을 신고할 수 있습니다.

인증

인증 사용 설정. 사용 설정하면 Pub/Sub에서 push 엔드포인트로 전달되는 메시지에는 엔드포인트가 요청을 인증할 수 있는 승인 헤더가 포함됩니다. 구독과 동일한 프로젝트에 호스팅된 App Engine 표준 및 Cloud Run 함수 엔드포인트에 자동 인증 및 승인 메커니즘을 사용할 수 있습니다.

인증된 push 구독의 인증 구성은 사용자 관리형 서비스 계정 및 create, patch, 또는 ModifyPushConfig 호출에 지정된 잠재고객 매개변수로 구성됩니다. 또한 다음 섹션에서 설명하는 것처럼 서비스 에이전트에 특정 역할을 부여해야 합니다.

사용자 관리형 서비스 계정(필수). push 구독과 관련된 서비스 계정입니다. 이 계정은 생성된 JSON 웹 토큰(JWT)의 email 클레임으로 사용됩니다. 다음은 서비스 계정의 요구사항 목록입니다.
- 이 서비스 계정은 push 구독과 동일한 프로젝트에 있어야 합니다.
- push 구독을 만들거나 수정하는 주 구성원은 서비스 계정에 대해 iam.serviceAccounts.actAs 권한이 있어야 합니다. 프로젝트, 폴더 또는 조직에 이 권한이 있는 역할을 부여하여 호출자가 여러 서비스 계정을 가장하도록 허용하거나 서비스 계정에 이 권한이 있는 역할 부여하여 호출자가 이 서비스 계정만 가장하도록 허용합니다.
잠재고객. 특정 토큰의 의도한 잠재고객을 검증하기 위해 웹훅에서 사용하는 대소문자를 구분하지 않는 단일 문자열입니다.
서비스 에이전트(필수).
- Pub/Sub는 service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com 형식으로 서비스 계정을 자동으로 만듭니다.
- Pub/Sub가 인증된 push 요청에 대한 JWT 토큰을 만들도록 허용하려면 이 서비스 에이전트에 roles/iam.serviceAccountTokenCreator 역할에 포함된 iam.serviceAccounts.getOpenIdToken 권한을 부여해야 합니다.

페이로드 래핑 해제

페이로드 래핑 해제 사용 설정 옵션은 메시지 데이터를 제외한 모든 메시지 메타데이터의 Pub/Sub 메시지를 제거합니다. 페이로드의 래핑을 해제하면 메시지 데이터가 HTTP 본문으로 직접 전달됩니다.

메타데이터 쓰기. 이전에 삭제된 메시지 메타데이터를 요청 헤더에 다시 추가합니다.

BigQuery 속성

구독 전송 유형을 BigQuery에 쓰기로 선택하면 다음과 같은 추가 속성을 지정할 수 있습니다.

주제 스키마 사용

이 옵션을 사용하면 Pub/Sub가 구독이 연결된 Pub/Sub 주제의 스키마를 사용할 수 있습니다. 또한 Pub/Sub가 BigQuery 테이블에서 해당 열에 메시지의 필드를 기록합니다.

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

주제 스키마 및 BigQuery 스키마의 필드가 이름이 동일하고 유형이 서로 호환되어야 합니다.
주제 스키마에서 선택적인 필드는 BigQuery 스키마에서도 선택적이어야 합니다.
주제 스키마의 필수 필드는 BigQuery 스키마에서 필수일 필요가 없습니다.
주제 스키마에 없는 BigQuery 필드가 있으면 이러한 BigQuery 필드가 NULLABLE 모드에 있어야 합니다.
주제 스키마에 BigQuery 스키마에 없는 추가 필드가 있고 이러한 필드를 생략할 수 있으면 알 수 없는 필드 삭제 옵션을 선택합니다.
구독 속성, 주제 스키마 사용 또는 테이블 스키마 사용 중에서 하나만 선택할 수 있습니다.

주제 스키마 사용 또는 테이블 스키마 사용 옵션을 선택하지 않는 경우에는 BigQuery 테이블에 BYTES, STRING 또는 JSON 유형의 data라는 열이 있는지 확인해야 합니다. Pub/Sub는 이 BigQuery 열에 메시지를 기록합니다.

Pub/Sub 주제 스키마 또는 BigQuery 테이블 스키마에 대한 변경사항이 BigQuery 테이블에 기록된 메시지에 즉시 적용되지 않을 수 있습니다. 예를 들어 알 수 없는 필드 삭제 옵션이 사용 설정되었고 필드가 Pub/Sub 스키마에 있지만 BigQuery 스키마에 없는 경우, BigQuery 테이블에 작성된 메시지는 BigQuery 스키마에 추가한 후에도 필드를 포함하지 않을 수 있습니다. 결국 스키마가 동기화되고 후속 메시지에 필드가 포함됩니다.

BigQuery 구독에 주제 스키마 사용 옵션을 사용하면 BigQuery 변경 데이터 캡처(CDC)를 활용할 수도 있습니다. CDC는 기존 행에 변경사항을 처리하고 적용하여 BigQuery 테이블을 업데이트합니다.

이 기능에 대한 자세한 내용은 변경 데이터 캡처로 테이블 업데이트 스트리밍을 참조하세요.

BigQuery 구독에서 이 기능을 사용하는 방법은 BigQuery 변경 데이터 캡처를 참조하세요.

테이블 스키마 사용

이 옵션을 사용하면 Pub/Sub에서 BigQuery 테이블의 스키마를 사용하여 JSON 메시지 필드를 해당 열에 쓸 수 있습니다. 이 옵션을 사용할 때는 다음 추가 요구사항을 확인해야 합니다.

게시된 메시지는 JSON 형식이어야 합니다.

다음과 같은 JSON 변환이 지원됩니다.

JSON 유형	BigQuery 데이터 유형
`string`	`STRING`, `BYTES`, `JSON`, `NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
`integer`	`INTEGER`, `NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
`float`	`FLOAT`, `NUMERIC` 또는 `BIGNUMERIC`

integer를 DATE, DATETIME, TIME, TIMESTAMP 변환에 사용할 때 정수가 지원되는 표현을 준수해야 합니다.
string을 NUMERIC 또는 BIGNUMERIC 변환에 사용할 때 Pub/Sub는 문자열이 인간이 읽을 수 있는 숫자(예: "123.124")라고 가정합니다. 문자열을 인간이 읽을 수 있는 숫자로 처리하지 못하면 Pub/Sub는 문자열을 BigDecimalByteStringEncoder로 인코딩된 바이트로 취급합니다.
string을 BYTES 변환에 사용할 때 문자열은 base64로 인코딩되어야 합니다.

구독 주제에 연결된 스키마가 있는 경우 메시지 인코딩 속성을 JSON으로 설정해야 합니다.
메시지에 없는 BigQuery 필드가 있으면 이러한 BigQuery 필드가 NULLABLE 모드에 있어야 합니다.
BigQuery 스키마에 없는 추가 필드가 메시지에 있고 이러한 필드를 삭제할 수 있으면 알 수 없는 필드 삭제 옵션을 선택합니다.
구독 속성, 주제 스키마 사용 또는 테이블 스키마 사용 중에서 하나만 선택할 수 있습니다.

BigQuery 테이블에 기록된 메시지와 함께 BigQuery 테이블 스키마 변경사항이 즉시 적용되지 않을 수도 있습니다. 예를 들어 알 수 없는 필드 삭제 옵션이 사용 설정되어 있고 필드가 메시지에 있지만 BigQuery 스키마에 없는 경우 필드를 BigQuery 스키마에 추가한 후에도 BigQuery 테이블에 기록된 메시지에는 여전히 필드가 포함되지 않을 수 있습니다. 결국 스키마가 동기화되고 후속 메시지에 필드가 포함됩니다.

BigQuery 구독에 테이블 스키마 사용 옵션을 사용하면 BigQuery 변경 데이터 캡처(CDC)를 활용할 수도 있습니다. CDC는 기존 행에 변경사항을 처리하고 적용하여 BigQuery 테이블을 업데이트합니다.

이 기능에 대한 자세한 내용은 변경 데이터 캡처로 테이블 업데이트 스트리밍을 참조하세요.

BigQuery 구독에서 이 기능을 사용하는 방법을 알아보려면 BigQuery 변경 데이터 캡처를 참조하세요.

알 수 없는 필드 삭제

이 옵션은 주제 스키마 사용 또는 테이블 스키마 사용 옵션과 함께 사용됩니다. 이 옵션을 사용하면 Pub/Sub에서 주제 스키마나 메시지에 있지만 BigQuery 스키마에 없는 필드를 삭제할 수 있습니다. 알 수 없는 필드 삭제를 설정하지 않으면 추가 필드가 있는 메시지가 BigQuery에 기록되지 않고 구독 백로그에 남게 됩니다. 구독이 결국 오류 상태가 됩니다.

메타데이터 쓰기

이 옵션을 사용하면 Pub/Sub가 각 메시지의 메타데이터를 BigQuery 테이블의 추가 열에 작성할 수 있습니다. 그렇지 않으면 메타데이터가 BigQuery 테이블에 작성되지 않습니다.

메타데이터 쓰기 옵션을 선택할 경우 BigQuery 테이블에 다음 테이블에 설명된 필드가 있는지 확인합니다.

메타데이터 쓰기 옵션을 선택하지 않으면 use_topic_schema가 true가 아닌 한 대상 BigQuery 테이블에 data 필드만 필요합니다. 메타데이터 쓰기 및 주제 스키마 사용 옵션을 모두 선택할 경우 주제 스키마에 메타데이터 매개변수와 일치하지 않는 이름의 필드가 포함되지 않아야 합니다. 이러한 제한사항에는 이러한 스네이크 표기법 매개변수의 카멜 표기법 버전이 포함됩니다.

매개변수
`subscription_name`	STRING 구독 이름입니다.
`message_id`	STRING 메시지 ID
`publish_time`	TIMESTAMP 메시지를 게시하는 시간입니다.
`data`	BYTES, STRING 또는 JSON 메시지 본문입니다. 주제 스키마 사용 또는 테이블 스키마 사용을 선택하지 않은 모든 대상 BigQuery 테이블에는 `data` 필드가 필요합니다. 필드가 JSON 유형이면 메시지 본문은 유효한 JSON이어야 합니다.
`attributes`	STRING 또는 JSON 모든 메시지 속성을 포함하는 JSON 객체입니다. 또한 순서 키(있는 경우)를 포함하여 Pub/Sub 메시지에 속하는 추가 필드를 포함합니다.

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)와 동일한 이름의 필드가 포함될 수 없습니다.

다음 단계

pull 구독 만들기
push 구독 만들기
BigQuery 구독 만들기
Cloud Storage 구독 만들기