이 페이지는 Cloud Translation API를 통해 번역되었습니다.

BigQuery 구독 만들기

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

시작하기 전에

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

구독 활용 방법
BigQuery 구독의 워크플로
메시지 오류 처리를 위해 데드 레터 주제를 구성하는 방법

Pub/Sub 및 BigQuery에 대한 기본 지식 외에도 BigQuery 구독을 만들기 전에 다음 기본 요건을 충족해야 합니다.

BigQuery 테이블이 있어야 합니다. 또는 이 문서의 뒷부분에 설명된 대로 BigQuery 구독을 만들 때 만들어도 됩니다.
Pub/Sub 주제의 스키마와 BigQuery 테이블 간 호환성이 있어야 합니다. 호환되지 않는 BigQuery 테이블을 추가하면 호환성 관련 오류 메시지가 표시됩니다. 자세한 내용은 스키마 호환성을 참조하세요.

필수 역할 및 권한

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

구독을 만들려면 프로젝트 수준에서 액세스 제어를 구성해야 합니다.
또한 이 섹션의 뒷부분에서 설명하는 것처럼 구독과 주제가 다른 프로젝트에 있는 경우 리소스 수준 권한도 필요합니다.
BigQuery 구독을 만들려면 Pub/Sub 서비스 에이전트 또는 커스텀 서비스 계정에 특정 BigQuery 테이블에 쓰기 권한이 있어야 합니다. 이러한 권한을 부여하는 방법에 대한 자세한 내용은 이 문서의 다음 섹션을 참고하세요.
프로젝트에 BigQuery 구독을 구성하여 다른 프로젝트의 BigQuery 테이블에 쓸 수 있습니다.

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

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

필수 권한

BigQuery 구독을 만들려면 다음 권한이 필요합니다.

구독에서 가져오기: pubsub.subscriptions.consume
구독 만들기: pubsub.subscriptions.create
구독 삭제: pubsub.subscriptions.delete
구독 가져오기: pubsub.subscriptions.get
구독 나열: pubsub.subscriptions.list
구독 업데이트: pubsub.subscriptions.update
주제에 구독 연결하기: pubsub.topics.attachSubscription
구독의 IAM 정책 가져오기: pubsub.subscriptions.getIamPolicy
구독의 IAM 정책 구성: pubsub.subscriptions.setIamPolicy

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

한 프로젝트의 주 구성원이 다른 프로젝트에서 BigQuery 구독을 만들 수 있도록 하려면 두 프로젝트 모두에서 해당 주 구성원에게 Pub/Sub 편집자 (roles/pubsub.editor) 역할을 부여해야 합니다. 이렇게 하면 새 BigQuery 구독을 만들고 원래 주제에 연결하는 데 필요한 권한이 제공됩니다. 주제에 대한 Pub/Sub 편집자 (roles/pubsub.editor) 역할은 다른 프로젝트의 BigQuery 구독을 주제에 연결하는 데도 도움이 됩니다.

서비스 계정에 역할 할당

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

Pub/Sub 서비스 에이전트 또는 커스텀 서비스 계정에 BigQuery 테이블에 쓰기 권한을 부여할 수 있습니다.

Pub/Sub 서비스 에이전트에게 권한을 부여하면 프로젝트에서 구독을 만들 권한이 있는 모든 사용자가 BigQuery 테이블에 쓸 수 있습니다. BigQuery 테이블에 쓰기 위한 더 세부적인 권한을 제공하려면 대신 맞춤 서비스 계정을 구성하세요.

BigQuery IAM에 대한 자세한 내용은 BigQuery 역할 및 권한을 참조하세요.

Pub/Sub 서비스 에이전트에 BigQuery 역할 할당

Pub/Sub 서비스 에이전트를 사용하여 BigQuery 구독을 만들려면 특정 BigQuery 테이블에 쓰기 권한과 테이블 메타데이터 읽기 권한이 있어야 합니다.

Pub/Sub 서비스 에이전트에 BigQuery 데이터 편집자 (roles/bigquery.dataEditor) 역할을 부여합니다. 개별 테이블 또는 프로젝트 전체에 권한을 부여할 수 있습니다.

표

Google Cloud 콘솔에서 BigQuery Studio로 이동합니다.

BigQuery Studio로 이동
탐색기 창의 이름 및 라벨로 필터링 검색창에 테이블 이름을 입력하고 Enter 키를 누릅니다.
권한을 부여할 표를 클릭합니다.
표에서 추가 작업 > 공유 > 권한을 선택합니다.

또는 표를 클릭하고 기본 페이지에서 공유 > 권한을 클릭합니다.

공유 권한 창이 열립니다.
주 구성원 추가를 클릭합니다.
주 구성원 추가에 구독이 포함된 프로젝트의 Pub/Sub 서비스 에이전트 이름을 입력합니다. 서비스 에이전트의 형식은 service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com입니다. 예를 들어 project-number=112233445566인 프로젝트의 경우 서비스 에이전트는 service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com 형식입니다.
역할 선택 드롭다운에서 BigQuery를 입력하고 BigQuery 데이터 편집자 역할을 선택합니다.
저장을 클릭합니다.

프로젝트

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

IAM으로 이동
액세스 권한 부여를 클릭합니다.
주 구성원 추가 섹션에 Pub/Sub 서비스 에이전트의 이름을 입력합니다. 서비스 에이전트의 형식은 service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com입니다. 예를 들어 project-number=112233445566인 프로젝트의 경우 서비스 에이전트는 service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com 형식입니다.
역할 할당 섹션에서 다른 역할 추가를 클릭합니다.
역할 선택 드롭다운에서 BigQuery를 입력하고 BigQuery 데이터 편집자 역할을 선택합니다.
저장을 클릭합니다.

커스텀 서비스 계정에 BigQuery 역할 할당

BigQuery 테이블에 쓰기 위해 커스텀 서비스 계정을 사용하려면 다음 권한을 설정해야 합니다.

커스텀 서비스 계정에는 특정 BigQuery 테이블에 쓰기 권한과 테이블 메타데이터 읽기 권한이 있어야 합니다.
Pub/Sub 서비스 에이전트에는 커스텀 서비스 계정에 대한 iam.serviceAccounts.getAccessToken 권한이 있어야 합니다.
구독을 만드는 사용자에게는 맞춤 서비스 계정에 대한 iam.serviceAccounts.actAs 권한이 있어야 합니다.

다음 단계에 따라 서비스 계정을 만들고 권한을 부여합니다.

커스텀 서비스 계정을 만듭니다. 서비스 계정은 구독과 동일한 프로젝트에 있어야 합니다.
맞춤 서비스 계정에 BigQuery 데이터 편집자 (roles/bigquery.dataEditor) 역할을 부여합니다.

프로젝트의 단일 테이블 또는 프로젝트의 모든 테이블에 서비스 계정 권한을 부여할 수 있습니다. 이렇게 하려면 Pub/Sub 서비스 에이전트에 BigQuery 역할 할당의 해당 섹션을 참고하세요. 절차에서 Pub/Sub 서비스 에이전트 이메일 주소를 맞춤 서비스 계정 이메일 주소로 바꿉니다.
커스텀 서비스 계정 또는 프로젝트의 모든 서비스 계정에 Pub/Sub 서비스 에이전트에게 iam.serviceAccounts.getAccessToken 권한을 부여합니다. Pub/Sub 서비스 에이전트에 roles/iam.serviceAccountTokenCreator 역할을 부여하여 이 권한을 부여할 수 있습니다.

요구사항에 따라 적절한 방법을 선택하세요.

서비스 계정

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

서비스 계정으로 이동
필터에 맞춤 서비스 계정의 이름을 입력합니다.
목록에서 서비스 계정을 선택합니다.
액세스 권한이 있는 주 구성원을 클릭합니다.
액세스 권한 부여를 클릭합니다.
주 구성원 추가 섹션에 구독이 포함된 프로젝트의 Pub/Sub 서비스 에이전트 이름을 입력합니다. 서비스 에이전트 형식은 service-project-number@gcp-sa-pubsub.iam.gserviceaccount.com입니다. 예를 들어 project-number=112233445566인 프로젝트의 경우 서비스 에이전트는 service-112233445566@gcp-sa-pubsub.iam.gserviceaccount.com 형식입니다.
역할 선택 드롭다운에 Service Account를 입력하고 서비스 계정 토큰 생성자 역할을 선택합니다.
저장을 클릭합니다.

프로젝트

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

IAM으로 이동
액세스 권한 부여를 클릭합니다.
주 구성원 추가 섹션에 맞춤 서비스 계정의 이름을 입력합니다.
역할 할당 섹션에서 다른 역할 추가를 클릭합니다.
역할 선택 드롭다운에 Service Account를 입력하고 서비스 계정 토큰 생성자 역할을 선택합니다.
저장을 클릭합니다.

맞춤 서비스 계정을 만든 경우 이미 필요한 iam.serviceAccounts.actAs 권한이 있을 것입니다. 다른 사용자에게 서비스 계정에 대한 권한을 부여해야 하는 경우 다음 단계를 따르세요.

Google Cloud 콘솔에서 서비스 계정 페이지로 이동합니다.

서비스 계정으로 이동
필터에 맞춤 서비스 계정의 이름을 입력합니다.
목록에서 서비스 계정을 선택합니다.
액세스 권한이 있는 주 구성원을 클릭합니다.
액세스 권한 부여를 클릭합니다.
주 구성원 추가 섹션에 액세스 권한을 부여할 계정의 이름을 입력합니다.
역할 선택 드롭다운에 Service Account를 입력하고 서비스 계정 사용자 역할을 선택합니다.
또한 BigQuery 테이블이 Apache Iceberg 테이블인 경우 Pub/Sub 서비스 계정에 Cloud Storage 버킷에 액세스할 수 있는 스토리지 관리자 역할 (roles/storage.admin)을 부여합니다.
저장을 클릭합니다.

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 메시지 필드를 해당 열에 쓸 수 있습니다. 이 옵션을 사용할 때는 다음 추가 요구사항을 확인해야 합니다.

BigQuery 테이블의 각 열 이름에는 문자 (a~z, A~Z), 숫자 (0~9) 또는 밑줄 (_)만 포함해야 합니다.
게시된 메시지는 JSON 형식이어야 합니다.

BigQuery 테이블 열의 데이터 유형이 JSON인 경우 Pub/Sub 메시지의 해당 필드는 이스케이프된 문자열의 유효한 JSON이어야 합니다. 예를 들어 myData이라는 열의 경우 메시지 필드는 "myData": "{\"key\":\"value\"}"이어야 합니다. BigQuery는 유효한 JSON이 포함되지 않은 메시지를 거부합니다.

다음 JSON 변환이 지원됩니다.

JSON 유형	BigQuery 데이터 유형
`string`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
`number`	`NUMERIC`, `BIGNUMERIC`, `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`

number를 DATE, DATETIME, TIME, TIMESTAMP 변환에 사용할 때 숫자가 지원되는 표현을 준수해야 합니다.
number를 NUMERIC 또는 BIGNUMERIC 변환에 사용할 때 값의 정밀도와 범위가 부동 소수점 산술을 위한 IEEE 754 표준에서 허용하는 값으로 제한됩니다. 높은 정밀도 또는 더 넓은 범위의 값이 필요한 경우 string을 NUMERIC 또는 BIGNUMERIC 변환에 대신 사용하세요.
string을 NUMERIC 또는 BIGNUMERIC 변환에 사용할 때 Pub/Sub는 문자열이 인간이 읽을 수 있는 숫자(예: "123.124")라고 가정합니다. 문자열을 인간이 읽을 수 있는 숫자로 처리하지 못하면 Pub/Sub는 문자열을 BigDecimalByteStringEncoder로 인코딩된 바이트로 취급합니다.

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

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

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

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

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

알 수 없는 필드 삭제

이 옵션은 주제 스키마 사용 또는 테이블 스키마 사용 옵션과 함께 사용됩니다. 이 옵션을 사용 설정하면 Pub/Sub에서 주제 스키마나 메시지에 있지만 BigQuery 스키마에는 없는 필드를 삭제할 수 있습니다. BigQuery 스키마에 포함되지 않은 필드는 BigQuery 테이블에 메시지를 쓸 때 삭제됩니다.

알 수 없는 필드 삭제를 설정하지 않으면 추가 필드가 있는 메시지가 BigQuery에 기록되지 않고 데드 레터 주제를 구성하지 않는 한 구독 백로그에 남게 됩니다.

알 수 없는 필드 삭제 설정은 Pub/Sub 주제 스키마나 BigQuery 테이블 스키마에 정의되지 않은 필드에는 영향을 미치지 않습니다. 이 경우 유효한 Pub/Sub 메시지가 구독에 전송됩니다. 하지만 BigQuery에는 이러한 추가 필드에 대해 정의된 열이 없으므로 BigQuery 쓰기 프로세스 중에 이러한 필드가 삭제됩니다. 이러한 동작을 방지하려면 Pub/Sub 메시지에 포함된 필드가 BigQuery 테이블 스키마에도 포함되어 있는지 확인하세요.

추가 필드에 관한 동작은 사용된 특정 스키마 유형(Avro, 프로토콜 버퍼) 및 인코딩 (JSON, 바이너리)에 따라 달라질 수도 있습니다. 이러한 요인이 추가 필드 처리에 미치는 영향에 대한 자세한 내용은 특정 스키마 유형 및 인코딩에 관한 문서를 참고하세요.

메타데이터 쓰기

이 옵션을 사용하면 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 메시지에 속하는 추가 필드를 포함합니다.

BigQuery 구독 만들기

다음 샘플은 BigQuery 전송을 사용하여 구독을 만드는 방법을 보여줍니다.

콘솔

Google Cloud 콘솔에서 구독 페이지로 이동합니다.

구독 페이지로 이동
구독 만들기를 클릭합니다.
구독 ID 필드에 이름을 입력합니다. 구독 이름 지정 방법은 주제 또는 구독 이름 지정 안내를 참고하세요.
드롭다운 메뉴에서 하나의 주제를 선택하거나 만듭니다. 구독은 주제에서 메시지를 수신합니다.
전송 유형을 BigQuery에 쓰기로 선택합니다.
BigQuery 테이블의 프로젝트를 선택합니다.
기존 데이터 세트를 선택하거나 새 항목을 만듭니다. 데이터 세트를 만드는 방법은 데이터 세트 만들기를 참조하세요.
기존 테이블을 선택하거나 새 항목을 만듭니다. 테이블을 만드는 방법은 테이블 만들기를 참조하세요.
메시지 오류를 처리하려면 데드 레터링을 사용 설정하는 것이 좋습니다. 자세한 내용은 데드 레터 주제를 참고하세요.
만들기를 클릭합니다.

주제 페이지에서도 구독을 만들 수 있습니다. 이 단축키는 주제를 구독과 연결하는 데 유용합니다.

Google Cloud 콘솔에서 주제 페이지로 이동합니다.

주제로 이동
구독을 만들려는 주제 옆에서 를 클릭합니다.
컨텍스트 메뉴에서 구독 만들기를 선택합니다.
전송 유형을 BigQuery에 쓰기로 선택합니다.
BigQuery 테이블의 프로젝트를 선택합니다.
기존 데이터 세트를 선택하거나 새 항목을 만듭니다. 데이터 세트를 만드는 방법은 데이터 세트 만들기를 참조하세요.
기존 테이블을 선택하거나 새 항목을 만듭니다. 데이터 세트를 만드는 방법은 테이블 만들기를 참조하세요.
메시지 오류를 처리하려면 데드 레터링을 사용 설정하는 것이 좋습니다. 자세한 내용은 데드 레터 주제를 참고하세요.
만들기를 클릭합니다.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

Pub/Sub 구독을 만들려면 gcloud pubsub subscriptions create 명령어를 사용합니다.
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID
```
커스텀 서비스 계정을 사용하려면 추가 인수로 제공하세요.
```
gcloud pubsub subscriptions create SUBSCRIPTION_ID \
    --topic=TOPIC_ID \
    --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID 
    --bigquery-service-account-email=SERVICE_ACCOUNT_NAME
```
다음을 바꿉니다.
- SUBSCRIPTION_ID: 구독 ID를 지정합니다.
- TOPIC_ID: 주제 ID를 지정합니다. 이 주제에는 스키마가 필요합니다.
- PROJECT_ID: 프로젝트의 ID를 지정합니다.
- DATASET_ID: 기존 데이터 세트의 ID를 지정합니다. 데이터 세트를 만들려면 데이터 세트 만들기를 참고하세요.
- TABLE_ID: 기존 테이블의 ID를 지정합니다. 주제에 스키마가 없으면 테이블에 data 필드가 필요합니다. 테이블을 만들려면 스키마 정의가 있는 빈 테이블 만들기를 참조하세요.
- SERVICE_ACCOUNT_NAME: BigQuery에 쓰기 위해 사용할 서비스 계정의 이름을 지정합니다.

C++

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

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& table_id) {
  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_bigquery_config()->set_table(table_id);
  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";
}

C#

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


using Google.Cloud.PubSub.V1;

public class CreateBigQuerySubscriptionSample
{
    public Subscription CreateBigQuerySubscription(string projectId, string topicId, string subscriptionId, string bigqueryTableId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            BigqueryConfig = new BigQueryConfig
            {
                Table = bigqueryTableId
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

다음 샘플에서는 Go Pub/Sub 클라이언트 라이브러리의 주요 버전 (v2)을 사용합니다. 아직 v1 라이브러리를 사용하고 있다면 v2로의 마이그레이션 가이드를 참고하세요. v1 코드 샘플 목록을 보려면 지원 중단된 코드 샘플을 참고하세요.

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

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createBigQuerySubscription creates a Pub/Sub subscription that exports messages to BigQuery.
func createBigQuerySubscription(w io.Writer, projectID, topic, subscription, table string) error {
	// projectID := "my-project"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// table := "my-project-id.dataset_id.table_id"
	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.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		BigqueryConfig: &pubsubpb.BigQueryConfig{
			Table:         table,
			WriteMetadata: true,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create subscription: %w", err)
	}
	fmt.Fprintf(w, "Created BigQuery subscription: %v\n", sub)

	return nil
}

자바

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

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.BigQueryConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateBigQuerySubscriptionExample {
  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 bigqueryTableId = "your-project.your-dataset.your-table";

    createBigQuerySubscription(projectId, topicId, subscriptionId, bigqueryTableId);
  }

  public static void createBigQuerySubscription(
      String projectId, String topicId, String subscriptionId, String bigqueryTableId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

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

      BigQueryConfig bigqueryConfig =
          BigQueryConfig.newBuilder().setTable(bigqueryTableId).setWriteMetadata(true).build();

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

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

Node.js

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

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId,
  subscriptionNameOrId,
  bigqueryTableId,
) {
  const options = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  bigqueryTableId: string,
) {
  const options: CreateSubscriptionOptions = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

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

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\V1\BigQueryConfig;

/**
 * Creates a Pub/Sub BigQuery subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $table      The BigQuery table to which to write.
 */
function create_bigquery_subscription($projectId, $topicName, $subscriptionName, $table)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = new BigQueryConfig(['table' => $table]);
    $subscription->create([
        'bigqueryConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

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

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "your-project.your-dataset.your-table"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

bigquery_config = pubsub_v1.types.BigQueryConfig(
    table=bigquery_table_id, write_metadata=True
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "bigquery_config": bigquery_config,
        }
    )

print(f"BigQuery subscription created: {subscription}.")
print(f"Table for subscription is: {bigquery_table_id}")

Ruby

다음 샘플에서는 Ruby Pub/Sub 클라이언트 라이브러리 v3을 사용합니다. 아직 v2 라이브러리를 사용하고 있는 경우 v3 마이그레이션 가이드를 참고하세요. Ruby v2 코드 샘플 목록을 보려면 지원 중단된 코드 샘플을 참고하세요.

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

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "my-project:dataset-id.table-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  bigquery_config: {
    table: bigquery_table_id,
    write_metadata: true
  }

puts "BigQuery subscription created: #{subscription_id}."
puts "Table for subscription is: #{bigquery_table_id}"

BigQuery 구독 모니터링

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

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

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

다음 단계

gcloud 명령어로 구독을 만들거나 수정합니다.
REST API로 구독을 만들거나 수정하기
BigQuery 구독 문제 해결하기