테이블 및 데이터 세트에 태그 지정

이 문서에서는 태그를 사용하여 BigQuery 테이블 및 데이터 세트에 Identity and Access Management(IAM) 정책을 조건부로 적용하는 방법을 설명합니다.

태그는 테이블 또는 데이터 세트에 직접 연결할 수 있거나 테이블 또는 데이터 세트가 다른 Google Cloud 리소스에서 상속할 수 있는 키-값 쌍입니다. 리소스에 특정 태그가 있는지 여부에 따라 정책을 조건부로 적용할 수 있습니다. 예를 들어 environment:dev 태그가 있는 모든 데이터 세트의 주 구성원에게 BigQuery 데이터 뷰어 역할을 조건부로 부여할 수 있습니다.

Google Cloud 리소스 계층 구조에서 태그 사용에 대한 자세한 내용은 태그 개요를 참조하세요.

아직 존재하지 않는 리소스를 포함하여 여러 관련 BigQuery 리소스에 동시에 권한을 부여하려면 IAM 조건을 사용하는 것이 좋습니다.

필수 권한

BigQuery에서 태그를 사용하려면 다음 권한이 필요합니다.

데이터 세트에 태그 연결하기 - 데이터 세트에 대한 bigquery.datasets.createTagBinding IAM 권한 및 연결하려는 태그 값에 대한 프로젝트 수준의 resourcemanager.tagValueBindings.create 권한이 필요합니다.
테이블에 태그 연결하기 - 테이블에 대한 bigquery.tables.createTagBinding IAM 권한 및 연결하려는 태그 값에 대한 프로젝트 수준의 resourcemanager.tagValueBindings.create 권한이 필요합니다.
데이터 세트에서 태그 삭제하기 - 데이터 세트에 대한 bigquery.datasets.deleteTagBinding IAM 권한 및 삭제할 태그 값에 대한 프로젝트 수준의 resourcemanager.tagValueBindings.delete 권한이 필요합니다.
테이블에서 태그 삭제하기 - 테이블에 대한 bigquery.tables.deleteTagBinding IAM 권한 및 삭제할 태그 값에 대한 프로젝트 수준의 resourcemanager.tagValueBindings.delete 권한이 필요합니다.
데이터 세트에 연결된 태그를 나열하거나 데이터 세트에 대한 세부정보 수정 패널에서 태그 섹션 보기 - bigquery.datasets.listTagBindings IAM 권한이 필요합니다.
데이터 세트 또는 테이블의 세부정보 수정 패널에서 상위 조직 또는 프로젝트와 연결된 태그 키를 나열하려면 태그 키의 상위 수준에 resourcemanager.tagKeys.list 권한 및 각 태그 키에 대해 resourcemanager.tagKeys.get 권한이 필요합니다.
데이터 세트 또는 테이블의 세부정보 수정 패널에서 상위 조직 또는 프로젝트와 연결된 키의 태그 값을 나열하려면 태그 값의 상위 수준에 resourcemanager.tagValues.list 권한 및 각 태그 값에 대해 resourcemanager.tagValues.get 권한이 필요합니다.

다음과 같은 사전 정의된 두 IAM 역할 모두에는 필요한 모든 BigQuery 권한이 포함되어 있습니다.

BigQuery 데이터 소유자(roles/bigquery.dataOwner)
BigQuery 관리자(roles/bigquery.admin)

Resource Manager 권한은 태그 사용자 역할(roles/resourcemanager.tagUser)에 포함됩니다.

태그 키 및 값 만들기

태그를 연결하려면 먼저 태그를 만들고 값을 구성해야 합니다. 태그 키와 태그 값을 만들려면 태그 만들기 및 태그 값 추가를 참조하세요.

데이터 세트에 태그 연결

태그를 만든 후 데이터 세트에 연결할 수 있습니다. 지정된 태그 키의 데이터 세트에 태그 값 하나만 연결할 수 있습니다. 데이터 세트에 태그를 최대 50개까지 연결할 수 있습니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트를 확장하고 데이터 세트를 선택합니다.
데이터 세트 정보 섹션에서 세부정보 수정을 클릭합니다.
태그 섹션에서 데이터 세트에 추가할 태그를 선택합니다.

참고: bigquery.datasets.listTagBindings 권한이 없으면 태그 섹션이 표시되지 않습니다.
저장을 클릭합니다.

gcloud

명령줄을 사용하여 태그를 데이터 세트에 연결하려면 gcloud resource-manager tags bindings create 명령어를 사용하여 태그 binding 리소스를 만듭니다.

gcloud resource-manager tags bindings create \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

다음을 바꿉니다.

TAGVALUE_NAME: 연결할 태그 값의 영구 ID 또는 네임스페이스 이름(예: tagValues/4567890123 또는 1234567/my_tag_key/my_tag_value)
RESOURCE_ID: 리소스 유형을 식별하는 API 도메인 이름(//bigquery.googleapis.com/)을 포함한 데이터 세트의 전체 ID(예: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset).
LOCATION: 데이터 세트 위치

데이터 세트에 연결된 태그 나열

다음 단계에서는 데이터 세트에 직접 연결된 태그 binding 목록을 제공합니다. 상위 리소스에서 상속된 태그는 반환되지 않습니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트를 확장하고 데이터 세트를 선택합니다.

태그가 데이터 세트 정보 섹션에 표시됩니다.

gcloud

리소스에 연결된 태그 binding 목록을 가져오려면 gcloud resource-manager tags bindings list 명령어를 사용합니다.

gcloud resource-manager tags bindings list \
    --parent=RESOURCE_ID \
    --location=LOCATION

다음을 바꿉니다.

RESOURCE_ID: 리소스 유형을 식별하는 API 도메인 이름(//bigquery.googleapis.com/)을 포함한 데이터 세트의 전체 ID(예: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset).
LOCATION: 데이터 세트 위치

출력은 다음과 비슷합니다.

name: tagBindings/%2F%2Fbigquery.googleapis.com%2Fprojects%2Fmy_project%2Fdatasets%2Fmy_dataset/tagValues/4567890123
parent: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset
tagValue: tagValues/4567890123

데이터 세트에서 태그 분리

태그 바인딩 리소스를 삭제하여 리소스에서 태그를 분리할 수 있습니다. 태그를 삭제해야 하는 경우 먼저 태그를 분리해야 합니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트를 확장하고 데이터 세트를 선택합니다.
데이터 세트 정보 섹션에서 세부정보 수정을 클릭합니다.
태그 섹션에서 삭제할 태그 옆에 있는 항목 삭제를 클릭합니다.
저장을 클릭합니다.

gcloud

명령줄을 사용하여 데이터 세트에서 태그를 분리하려면 gcloud alpha resource-manager tags bindings delete 명령어를 사용하여 태그 binding을 삭제합니다.

gcloud alpha resource-manager tags bindings delete \
    --tag-value=TAGVALUE_NAME \
    --parent=RESOURCE_ID \
    --location=LOCATION

다음을 바꿉니다.

TAGVALUE_NAME: 연결할 태그 값의 영구 ID 또는 네임스페이스 이름(예: tagValues/4567890123 또는 1234567/my_tag_key/my_tag_value)
RESOURCE_ID: 리소스 유형을 식별하는 API 도메인 이름(//bigquery.googleapis.com/)을 포함한 데이터 세트의 전체 ID(예: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset).
LOCATION: 데이터 세트 위치

새 테이블을 만들 때 태그 연결

태그를 만든 후 새 테이블에 연결할 수 있습니다. 지정된 태그 키의 데이터 세트에 태그 값 하나만 연결할 수 있습니다. 테이블에 태그를 최대 50개까지 연결할 수 있습니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트를 펼친 후 데이터 세트를 선택합니다.
데이터 세트 정보 섹션에서 테이블 만들기를 클릭합니다.
새 테이블에 대한 정보를 입력합니다. 자세한 내용은 테이블 만들기 및 사용을 참조하세요.
태그 섹션에서 새 테이블에 추가할 태그를 선택합니다. 이 단계에서는 태그 ID를 수동으로 입력할 수 없습니다. 프로젝트 또는 조직의 태그만 선택할 수 있습니다.
테이블 만들기를 클릭합니다.

bq

--add_tags 플래그와 함께 bq mk --table 명령어를 사용합니다.

bq mk --table \
    --schema=SCHEMA \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

다음을 바꿉니다.

SCHEMA: 인라인 스키마 정의입니다.
TAGS: 새 테이블에 연결할 태그이며 쉼표로 구분됩니다(예: 556741164180/env:prod,myProject/department:sales). 각 태그에는 네임스페이스화된 키 이름과 값 닉네임이 있어야 합니다.
PROJECT_ID: 테이블을 만들 프로젝트의 ID입니다.
DATASET_ID: 테이블을 만들 데이터 세트의 ID입니다.
TABLE_ID: 만들려는 새 테이블의 ID입니다.

API

테이블 리소스가 정의된 tables.insert 메서드를 호출하고 resource_tags 필드에 태그를 포함합니다.

기존 테이블에 태그 연결

태그를 만든 후 기존 테이블에 연결할 수 있습니다. 지정된 태그 키의 테이블에는 태그 값 하나만 연결할 수 있습니다. 테이블에 태그를 최대 50개까지 연결할 수 있습니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트와 데이터 세트를 펼친 후 테이블을 선택합니다.
세부정보 탭에서 세부정보 수정을 클릭합니다.
태그 섹션에서 테이블에 추가할 태그를 선택합니다. 이 단계에서는 태그 ID를 수동으로 입력할 수 없습니다. 프로젝트 또는 조직의 태그만 선택할 수 있습니다.
저장을 클릭합니다.

bq

--add_tags 플래그와 함께 bq update 명령어를 사용합니다.

bq update \
    --add_tags=TAGS \
    PROJECT_ID:DATASET_ID.TABLE_ID

다음을 바꿉니다.

TAGS: 테이블에 연결할 태그로 쉼표로 구분됩니다(예: 556741164180/env:prod,myProject/department:sales). 각 태그에는 네임스페이스화된 키 이름과 값 닉네임이 있어야 합니다.
PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
DATASET_ID: 테이블이 포함된 데이터 세트의 ID입니다.
TABLE_ID: 업데이트할 테이블의 ID입니다.

API

테이블 리소스가 정의된 tables.update 메서드를 호출하고 resource_tags 필드에 태그를 포함합니다.

테이블에 연결된 태그 나열

테이블에 직접 연결된 태그를 나열할 수 있습니다. 이 프로세스에서는 상위 리소스에서 상속된 태그를 나열하지 않습니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트와 데이터 세트를 펼친 후 테이블을 선택합니다.

태그는 세부정보 탭에 표시됩니다.

bq

bq show 명령어를 사용하고 tags 열을 찾습니다. 테이블에 태그가 없으면 tags 열이 표시되지 않습니다.

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

다음을 바꿉니다.

PROJECT_ID: 테이블이 포함된 프로젝트의 ID
DATASET_ID: 테이블이 포함된 데이터 세트의 ID
TABLE_ID: 테이블의 ID

API

테이블 리소스가 정의된 tables.get 메서드를 호출하고 resource_tags 필드를 찾습니다.

테이블에서 태그 분리

태그 바인딩 리소스를 삭제하여 테이블에서 태그를 분리할 수 있습니다. 태그를 삭제해야 하는 경우 먼저 태그를 분리해야 합니다.

콘솔

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

BigQuery로 이동
탐색기 창에서 프로젝트와 데이터 세트를 펼친 후 테이블을 선택합니다.
세부정보 탭에서 세부정보 수정을 클릭합니다.
태그 섹션에서 테이블에서 분리하려는 태그를 삭제합니다.
저장을 클릭합니다.

bq

테이블에서 일부 태그를 삭제하려면 bq update 명령어를 --remove_tags 플래그와 함께 사용합니다.

bq update \
    --remove_tags=TAG_KEYS \
    PROJECT_ID:DATASET_ID.TABLE_ID

다음을 바꿉니다.

TAG_KEYS: 쉼표로 구분된 테이블에서 분리하는 태그 키입니다(예: 556741164180/env,myProject/department). 각 태그 키에는 네임스페이스화된 키 이름이 있어야 합니다.
PROJECT_ID: 테이블이 포함된 프로젝트의 ID입니다.
DATASET_ID: 테이블이 포함된 데이터 세트의 ID입니다.
TABLE_ID: 업데이트할 테이블의 ID입니다.

테이블에서 모든 태그를 삭제하려면 bq update 명령어를 --clear_all_tags 플래그와 함께 사용합니다.

bq update \
    --clear_all_tags \
    PROJECT_ID:DATASET_ID.TABLE_ID

API

테이블 리소스가 정의된 tables.update 메서드를 호출하고 resource_tags 필드에서 태그를 삭제합니다. 모든 태그를 삭제하려면 resource_tags 필드를 삭제합니다.

태그 삭제

데이터 세트 또는 테이블에서 참조되는 태그는 삭제할 수 없습니다. 태그 키나 값 자체를 삭제하기 전에 기존 모든 태그 바인딩 리소스를 분리해야 합니다. 태그 키와 태그 값을 삭제하려면 태그 삭제를 참조하세요.

예시

조직의 관리자라고 가정해 보겠습니다. 데이터 분석가는 프로젝트 userData에 대한 BigQuery 데이터 뷰어 IAM 역할이 있는 analysts@example.com 그룹의 모든 구성원입니다. 데이터 분석가 인턴은 채용되며 회사 정책에 따라 userData 프로젝트에서 anonymousData 데이터 세트를 볼 수 있는 권한만 부여받아야 합니다. 태그를 사용하여 액세스를 제어할 수 있습니다.

키가 employee_type이고 값이 intern인 태그를 만듭니다.
Google Cloud Console에서 IAM 페이지로 이동합니다.

IAM으로 이동
제한하려는 데이터 세트 액세스 권한이 있는 인턴이 포함된 행을 찾고 이 행에서 주 구성원 수정을 클릭합니다.
역할 메뉴에서 BigQuery 데이터 뷰어를 선택합니다.
조건 추가를 클릭합니다.
제목 필드와 설명 필드에 만들려는 IAM 태그 조건을 설명하는 값을 입력합니다.
조건 작성 도구 탭에서 추가를 클릭합니다.
조건 유형 메뉴에서 리소스를 선택한 후 태그를 선택합니다.
연산자 메뉴에서 값 있음을 선택합니다.
값 경로 필드에 ORGANIZATION/TAG_KEY/TAG_VALUE 형식으로 태그 값 경로(예: example.org/employee_type/intern)를 입력합니다.

이 IAM 태그 조건은 intern 태그가 있는 데이터 세트에 대한 인턴의 액세스 권한을 제한합니다.
태그 조건을 저장하려면 저장을 클릭합니다.
권한 수정 창에서 변경한 모든 사항을 저장하려면 저장을 클릭합니다.

intern 태그 값을 anonymousData 데이터 세트에 연결하려면 명령줄을 사용하여 gcloud alpha resource-manager tags bindings create 명령어를 실행합니다.

gcloud alpha resource-manager tags bindings create \
--tag-value=tagValues/4567890123 \
--parent=//bigquery.googleapis.com/projects/userData/datasets/anonymousData \
--location=US

제한사항

테이블 태그는 BigQuery Omni 테이블, 숨겨진 데이터 세트의 테이블, 임시 테이블에서 지원되지 않습니다. 또한 BigQuery Omni의 리전 간 쿼리는 다른 리전의 테이블에 대한 액세스 제어 검사 중에 태그를 사용하지 않습니다.
Cloud Resource Manager API에 테이블 태그를 사용할 수 없습니다.
데이터 세트 또는 테이블에 태그를 최대 50개까지 연결할 수 있습니다.
태그가 있는 테이블에는 와일드 카드 쿼리가 지원되지 않습니다.
BigQuery 외부의 일부 서비스는 IAM 태그 조건을 올바르게 확인할 수 없습니다. 태그 조건이 양수인 경우, 즉 리소스에 특정 태그가 있는 경우에만 사용자에게 리소스에 대한 역할이 부여되는 경우, 연결된 태그에 관계없이 리소스에 대한 액세스가 거부됩니다. 태그 조건이 부정인 경우, 즉 해당 리소스에 특정 태그가 없는 경우에만 사용자에게 리소스에 대한 역할이 부여되는 경우에는 태그 조건을 확인하지 않습니다.

예를 들어 Data Catalog는 BigQuery 데이터 세트에서 IAM 태그 조건을 확인할 수 없습니다. employee_type=intern 태그가 있는 데이터 세트에 대한 BigQuery 데이터 뷰어 역할을 인턴에게 부여하는 조건부 IAM 정책이 있다고 가정해 보겠습니다. 양수 태그 조건이므로 데이터 세트에 employee_type=intern 태그가 있어도 인턴이 Data Catalog에서 검색하여 데이터 세트를 볼 수 없습니다. 태그 조건이 부정으로 변경되어 인턴 직원이 employee_type=intern 태그가 없는 데이터 세트만 볼 수 있다면, 확인을 완전히 건너뛰게 되고 인턴은 평소에는 BigQuery에서 액세스할 수 없었던 데이터 세트를 볼 수 있게 됩니다.

권장사항: 의도치 않게 역할이 부여되는 것을 방지하려면 음의 조건이 아닌 양의 IAM 태그 조건을 사용하세요.

다음 단계

Google Cloud의 태그에 대한 개요는 태그 개요를 참조하세요.
태그 사용 방법에 대한 자세한 내용은 태그 생성 및 관리를 참조하세요.
IAM 조건으로 BigQuery 리소스에 대한 액세스를 제어하는 방법은 IAM 조건으로 액세스 제어를 참조하세요.