テーブルとデータセットにタグを付ける

このドキュメントでは、タグを使用して Identity and Access Management(IAM)ポリシーを BigQuery テーブルとデータセットに条件付きで適用する方法について説明します。

タグは、テーブルまたはデータセットに直接適用できる Key-Value ペア、またはテーブルまたはデータセットが他の Google Cloud リソースから継承できる Key-Value ペアです。リソースに特定のタグが付加されているかどうかに基づいて、条件付きでポリシーを適用できます。たとえば、environment:dev タグの付いた任意のデータセットのプリンシパルに、BigQuery データ閲覧者のロールを条件付きで付与できます。

Google Cloud リソース階層全体でタグを使用する方法については、タグの概要をご覧ください。

まだ存在しないリソースを含め、関連する多くの BigQuery リソースに権限を同時に付与する場合は、IAM Conditions の使用を検討してください。

始める前に

このドキュメントの各タスクを実行するために必要な権限をユーザーに付与する IAM ロールを付与する必要があります。また、リソースに適用するタグキーとタグ値を作成する必要があります。

必要な権限

BigQuery でタグを使用するには、次の権限が必要です。

  • タグをテーブルに適用するには、テーブルに対する bigquery.tables.createTagBinding IAM 権限と、添付するタグ値に対するプロジェクト レベルの resourcemanager.tagValueBindings.create 権限が必要です。
  • タグをデータセットに適用するには、データセットに対する bigquery.datasets.createTagBinding IAM 権限と、添付するタグ値に対するプロジェクト レベルの resourcemanager.tagValueBindings.create 権限が必要です。
  • タグをテーブルから削除するには、テーブルに対する bigquery.tables.deleteTagBinding IAM 権限と、削除するタグ値に対するプロジェクト レベルの resourcemanager.tagValueBindings.delete 権限が必要です。
  • タグをデータセットから削除するには、データセットに対する bigquery.datasets.deleteTagBinding IAM 権限と、削除するタグ値に対するプロジェクト レベルの resourcemanager.tagValueBindings.delete 権限が必要です。
  • テーブルまたはデータセットの [詳細を編集] パネルで、親組織またはプロジェクトに関連付けられているタグキーを一覧表示するには、タグキーの親レベルの resourcemanager.tagKeys.list 権限と、各タグキーの resourcemanager.tagKeys.get 権限が必要になります。
  • テーブルまたはデータセットの [詳細を編集] パネルの親組織またはプロジェクトに関連付けられているキーのタグ値を一覧表示するには、タグの親レベルの resourcemanager.tagValues.list 権限および各タグ値の resourcemanager.tagValues.get 権限が必要です。

Cloud Resource Manager API または gcloud でタグを使用している場合は、次の権限も必要です。

  • Cloud Resource Manager API または gcloud CLI を使用してテーブルに適用されているタグを一覧表示するには、bigquery.tables.listTagBindings IAM 権限が必要です。
  • テーブルの有効なタグを一覧表示するには、bigquery.tables.listEffectiveTags IAM 権限が必要です。
  • Cloud Resource Manager API または gcloud CLI を使用してデータセットに適用されているタグを一覧表示するには、bigquery.datasets.listTagBindings IAM 権限が必要です。
  • データセットの有効なタグを一覧表示するには、bigquery.datasets.listEffectiveTags IAM 権限が必要です。

次の IAM 事前定義ロールには、必要な BigQuery の権限がすべて含まれています。

  • BigQuery データオーナー(roles/bigquery.dataOwner
  • BigQuery 管理者(roles/bigquery.admin

Resource Manager の権限は、タグユーザー ロール(roles/resourcemanager.tagUser)に含まれています。

タグを使用すると、IAM ポリシーで BigQuery テーブルとデータセットに対して、条件付きでアクセスを拒否することもできます(プレビュー)。詳細については、拒否ポリシーをご覧ください。

タグキーとタグ値を作成する

タグを適用する前に、タグを作成してその値を構成する必要があります。タグキーとタグ値を作成するには、タグの作成タグ値の追加をご覧ください。

テーブルにタグを付ける

以降のセクションでは、新しいテーブルと既存のテーブルにタグを適用する方法、テーブルに適用されているタグを一覧表示する方法、テーブルからタグを削除する方法について説明します。

新しいテーブルの作成時にタグを適用する

タグを作成したら、新しいテーブルに適用できます。任意のタグキーのテーブルに適用できるタグ値は 1 つのみです。テーブルに適用できるタグは最大 50 個までです。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開き、データセットを選択します。

  3. [データセット情報] セクションで、[テーブルを作成] をクリックします。

  4. 新しいテーブルの情報を入力します。詳細については、テーブルの作成と使用をご覧ください。

  5. [タグ] セクションで、新しいテーブルに追加するタグを選択します。

  6. [テーブルを作成] をクリックします。

bq

--add_tags フラグを指定して bq mk --table コマンドを使用します。

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

次のように置き換えます。

  • SCHEMA: インライン スキーマの定義
  • TAG: 新しいテーブルに付加するタグ。複数のタグを指定する場合はカンマで区切ります。例: 556741164180/env:prod,myProject/department:sales。各タグには、名前空間付きのキー名と値の略称が必要です。
  • PROJECT_ID: テーブルを作成するプロジェクトの ID。
  • DATASET_ID: テーブルを作成するデータセットの ID。
  • TABLE_ID: 作成する新しいテーブルの ID。

API

定義済みのテーブル リソースを使用して tables.insert メソッドを呼び出し、resource_tags フィールドにタグを含めます。

既存のテーブルにタグを適用する

タグを作成したら、既存のテーブルに適用できます。任意のタグキーのテーブルに適用できるタグ値は 1 つのみです。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトとデータセットを開いて、テーブルを選択します。

  3. [詳細] タブで、 [詳細を編集] をクリックします。

  4. [タグ] セクションで、テーブルに追加するタグを選択します。

  5. [保存] をクリックします。

bq

--add_tags フラグを指定して bq update コマンドを使用します。

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

次のように置き換えます。

  • TAG: テーブルに付加するタグ。複数のタグを指定する場合はカンマで区切ります。例: 556741164180/env:prod,myProject/department:sales。各タグには、名前空間付きのキー名と値の略称が必要です。
  • PROJECT_ID: テーブルを含むプロジェクトの ID。
  • DATASET_ID: テーブルを含むデータセットの ID。
  • TABLE_ID: 更新するテーブルの ID。

gcloud

コマンドラインを使用してテーブルにタグを適用するには、gcloud resource-manager tags bindings create コマンドを使用してタグ バインディング リソースを作成します。

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

次のように置き換えます。

  • TAGVALUE_NAME: 適用するタグ値の永続 ID または名前空間付きの名前(tagValues/45678901231234567/my_tag_key/my_tag_value など)。
  • RESOURCE_ID: リソースのタイプを識別するための API ドメイン名(//bigquery.googleapis.com/)を含む、テーブルの完全な ID。例: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset/my_table
  • LOCATION: テーブルのロケーション

API

定義済みのテーブル リソースを使用して tables.update メソッドを呼び出し、resource_tags フィールドにタグを含めます。

テーブルに適用されたタグを一覧表示する

テーブルに直接適用されているタグを一覧表示できます。このプロセスでは、親リソースから継承されたタグは一覧表示されません。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトとデータセットを開いて、テーブルを選択します。

    タグは [詳細] タブに表示されます。

bq

bq show コマンドを使用して、tags 列を探します。テーブルにタグがない場合、tags 列は表示されません。

bq show \
    PROJECT_ID:DATASET_ID.TABLE_ID

次のように置き換えます。

  • PROJECT_ID: テーブルを含むプロジェクトの ID。
  • DATASET_ID: テーブルを含むデータセットの ID。
  • TABLE_ID: テーブルの ID。

gcloud

リソースに適用されたタグ バインディングのリストを取得するには、次のように 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/my_table

  • 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

API

定義済みのテーブル リソースを使用して tables.get メソッドを呼び出し、resource_tags フィールドを探します。

ビュー

INFORMATION_SCHEMA.TABLE_OPTIONS ビューを使用します。

たとえば、次のクエリは、データセット内のすべてのテーブルに適用されているすべてのタグを示します。このクエリは、schema_name(データセット名)、option_name(常に 'tags')、object_type(常に ARRAY<STRUCT<STRING, STRING>>)、option_value を含む列があるテーブルを返します。これには、各データセットに関連付けられたタグを表す STRUCT オブジェクトの配列が含まれます。タグが割り当てられていないテーブルの場合、option_value 列は空の配列を返します。

SELECT * from DATASET_ID.INFORMATION_SCHEMA.TABLE_OPTIONS
WHERE option_name='tags'

DATASET_ID は、テーブルを含むデータセットの ID に置き換えます。

テーブルからタグの適用を解除する

テーブルからタグの関連付けを削除するには、タグ バインディングを削除します。タグを削除する必要がある場合は、まずタグの適用を解除する必要があります。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、プロジェクトとデータセットを開いて、テーブルを選択します。

  3. [詳細] タブで、 [詳細を編集] をクリックします。

  4. [タグ] セクションで、テーブルから切断するタグを削除します。

  5. [保存] をクリックします。

bq

テーブルから一部のタグを削除するには、--remove_tags フラグを指定して bq update コマンドを使用します。

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。

テーブルからすべてのタグを削除するには、--clear_all_tags フラグを指定して bq update コマンドを使用します。

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

gcloud

コマンドラインを使用してテーブルからタグの関連付けを削除するには、gcloud resource-manager tags bindings delete コマンドを使用してタグ バインディングを削除します。

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

次のように置き換えます。

  • TAGVALUE_NAME: 削除するタグ値の永続 ID または名前空間付きの名前(tagValues/45678901231234567/my_tag_key/my_tag_value など)。
  • RESOURCE_ID: リソースのタイプを識別する API ドメイン名(//bigquery.googleapis.com/)を含む、テーブルの完全な ID。例: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset/my_table
  • LOCATION: データセットのロケーション

API

定義済みのテーブル リソースを使用して tables.update メソッドを呼び出し、resource_tags フィールドのタグを削除します。すべてのタグを削除するには、resource_tags フィールドを削除します。

データセットにタグを付ける

以降のセクションでは、新しいデータセットと既存のデータセットにタグを適用する方法、データセットに適用されたタグを一覧表示する方法、データセットからタグを削除する方法について説明します。

新しいデータセットの作成時にタグを適用する

タグを作成したら、新しい BigQuery データセットに適用できます。任意のタグキーのデータセットに適用できるタグ値は 1 つのみです。データセットに適用できるタグは最大 50 個までです。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインで、データセットを作成するプロジェクトを選択します。

  3. more_vert [アクションを表示] > [データセットを作成] をクリックします。

  4. [タグ] メニューで [スコープの選択] をクリックします。

  5. タグのスコープを選択します。

  6. データセットに追加するタグを選択して追加します。

  7. [データセットを作成] をクリックします。

bq

--add_tags フラグを指定して bq mk --dataset コマンドを使用します。

bq mk --dataset \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID

次のように置き換えます。

  • TAG: 新しいデータセットに適用するタグ。複数のタグを指定する場合はカンマで区切ります。例: 556741164180/env:prod,myProject/department:sales。各タグには、名前空間付きのキー名と値の略称が必要です。
  • PROJECT_ID: データセットを作成するプロジェクトの ID。
  • DATASET_ID: 作成する新しいデータセットの ID。

API

datasets.insert メソッドを呼び出して、タグを resource_tags フィールドに追加します。

既存のデータセットにタグを適用する

タグを作成したら、既存のデータセットに適用できます。任意のタグキーのデータセットに適用できるタグ値は 1 つのみです。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開いて、データセットを選択します。

  3. [データセット情報] セクションで、 [詳細を編集] をクリックします。

  4. [タグ] セクションで、データセットに追加するタグを選択します。

  5. [保存] をクリックします。

bq

--add_tags フラグを指定して bq update コマンドを使用します。

bq update \
    --add_tags=TAG \
    PROJECT_ID:DATASET_ID

次のように置き換えます。

  • TAG: データセットに適用するタグ。複数のタグを指定する場合はカンマで区切ります。例: 556741164180/env:prod,myProject/department:sales。各タグには、名前空間付きのキー名と値の略称が必要です。
  • PROJECT_ID: 既存のデータセットが配置されているプロジェクトの ID。
  • DATASET_ID: 既存のデータセットの ID。

gcloud

コマンドラインを使用してデータセットにタグを適用するには、gcloud resource-manager tags bindings create コマンドを使用してタグ バインディング リソースを作成します。

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

次のように置き換えます。

  • TAGVALUE_NAME: 適用するタグ値の永続 ID または名前空間付きの名前(tagValues/45678901231234567/my_tag_key/my_tag_value など)。
  • RESOURCE_ID: リソースのタイプを識別するための API ドメイン名(//bigquery.googleapis.com/)を含む、データセットの完全な ID(例: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset)。
  • LOCATION: データセットのロケーション

API

datasets.get メソッドを呼び出して、resource_tags フィールドを含むデータセット リソースを取得します。タグを resource_tags フィールドに追加し、datasets.update メソッドを使用して更新されたデータセット リソースを返します。

データセットに適用されたタグを一覧表示する

次の手順では、データセットに直接適用されているタグ バインディングのリストを示します。親リソースから継承されたタグは返されません。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開いて、データセットを選択します。

    タグが [データセット情報] セクションに表示されます。

bq

データセットに適用されているタグを一覧表示するには、bq show コマンドを使用します。

bq show PROJECT_ID:DATASET_ID

次のように置き換えます。

  • PROJECT_ID: データセットを含むプロジェクトの ID。
  • DATASET_ID: タグを一覧表示するデータセットの ID。

gcloud

リソースに適用されたタグ バインディングのリストを取得するには、次のように 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

API

datasets.get メソッドを呼び出して、データセット リソースを取得します。データセット リソースには、resource_tags フィールドでデータセットに適用されているタグが含まれています。

ビュー

INFORMATION_SCHEMA.SCHEMATA_OPTIONS ビューを使用します。

たとえば、次のクエリは、リージョン内のすべてのデータセットに適用されているすべてのタグを表示します。このクエリは、schema_name(データセット名)、option_name(常に 'tags')、object_type(常に ARRAY<STRUCT<STRING, STRING>>)、option_value を含む列があるテーブルを返します。これには、各データセットに関連付けられたタグを表す STRUCT オブジェクトの配列が含まれます。タグが割り当てられていないデータセットの場合、option_value 列は空の配列を返します。

SELECT * from region-REGION.INFORMATION_SCHEMA.SCHEMATA_OPTIONS
WHERE option_name='tags'

次のように置き換えます。

データセットからタグの適用を解除する

タグ バインディング リソースを削除すると、リソースからタグの適用を解除できます。タグを削除する必要がある場合は、まずタグの適用を解除する必要があります。

コンソール

  1. Google Cloud コンソールで [BigQuery] ページに移動します。

    [BigQuery] に移動

  2. [エクスプローラ] ペインでプロジェクトを開いて、データセットを選択します。

  3. [データセット情報] セクションで、 [詳細を編集] をクリックします。

  4. [タグ] セクションで、削除するタグの横にある [項目を削除] をクリックします。

  5. [保存] をクリックします。

bq

--remove_tags フラグを指定して bq update コマンドを使用します。

bq update \
    --remove_tags=REMOVED_TAG \
    PROJECT_ID:DATASET_ID

次のように置き換えます。

  • REMOVED_TAG: データセットから削除するタグ。複数のタグを指定する場合はカンマで区切ります。値のペアのないキーのみを受け入れます。例: 556741164180/env,myProject/department。各タグには名前空間付きのキー名が必要です。
  • PROJECT_ID: データセットを含むプロジェクトの ID。
  • DATASET_ID: タグを取り外すデータセットの ID。

データセットからすべてのタグを削除する場合は、--clear_all_tags フラグを指定して bq update コマンドを使用します。

bq update \
    --clear_all_tags
    PROJECT_ID:DATASET_ID

gcloud

コマンドラインを使用してデータセットからタグの適用を解除するには、gcloud resource-manager tags bindings delete コマンドを使用してタグ バインディングを削除します。

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

次のように置き換えます。

  • TAGVALUE_NAME: 適用を解除するタグ値の永続 ID または名前空間付きの名前(tagValues/45678901231234567/my_tag_key/my_tag_value など)。
  • RESOURCE_ID: リソースのタイプを識別するための API ドメイン名(//bigquery.googleapis.com/)を含む、データセットの完全な ID(例: //bigquery.googleapis.com/projects/my_project/datasets/my_dataset)。
  • LOCATION: データセットのロケーション

API

datasets.get メソッドを呼び出して、resource_tags フィールドを含むデータセット リソースを取得します。resource_tags フィールドからタグを削除し、datasets.update メソッドを使用して更新されたデータセット リソースを返します。

タグを削除する

テーブルまたはデータセットから参照されているタグは削除できません。タグのキーまたは値自体を削除する前に、既存のタグ バインディング リソースをすべて解除する必要があります。タグキーとタグ値を削除するには、タグの削除をご覧ください。

たとえば、組織の管理者であるとします。組織のデータ アナリストはすべてグループ analysts@example.com のメンバーで、プロジェクトの userData に対して BigQuery データ閲覧者 IAM ロールを持ちます。データ アナリストのインターンが 1 名雇用されています。このインターンには、会社のポリシーに従って、userData プロジェクトの anonymousData データセットを表示する権限のみが付与されます。タグを使用してこれらのメンバーのアクセスを制御できます。

  1. キー employee_type と値 intern を使用してタグを作成します

    タグキーとタグ値の作成例。

  2. Google Cloud コンソールの [IAM] ページに移動します。

    [IAM] に移動

  3. データセットへのアクセスを制限するインターンを含む行を見つけて、その行の [プリンシパルを編集] をクリックします。

  4. [ロール] メニューから [BigQuery データ閲覧者] を選択します。

  5. [条件を追加] をクリックします。

  6. [タイトル] フィールドと [説明] フィールドに、作成する IAM タグの条件を説明する値を入力します。

  7. [条件作成ツール] タブで [追加] をクリックします。

  8. [条件タイプ] メニューで、[リソース]、[タグ] の順に選択します。

  9. [演算子] メニューで [値を持つ] を選択します。

  10. [値のパス] フィールドに、ORGANIZATION/TAG_KEY/TAG_VALUE の形式でタグ値のパスを入力します(例: example.org/employee_type/intern)。

    タグを使用した IAM 条件の例。

    この IAM タグ条件によって、intern タグを持つデータセットに対するインターンのアクセスが制限されます。

  11. タグ条件を保存するには、[保存] をクリックします。

  12. [権限を編集] ペインで行ったすべての変更を保存するには、[保存] をクリックします。

  13. intern タグの値を anonymousData データセットに適用するには、コマンドラインを使用して gcloud resource-manager tags bindings create コマンドを実行します。

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

制限事項

  • テーブルタグは、BigQuery Omni テーブル、非表示データセットのテーブル、一時テーブルではサポートされていません。また、BigQuery Omni のクロスリージョン クエリでは、他のリージョンのテーブルのアクセス制御チェック中にタグを使用しません。

  • テーブルまたはデータセットに適用できるタグは最大 50 個です。

  • ワイルドカード クエリで参照されるすべてのテーブルは、タグキーと値の組が完全に同じでなければなりません。

  • BigQuery の外部のサービスには、IAM タグ条件を適切に検証できないものもあります。タグ条件が正の場合、つまり、そのリソースに特定のタグがあるときだけ、ユーザーにそのリソースのロールが付与される場合、適用されているタグに関係なく、リソースへのアクセスは拒否されます。タグ条件が負の場合、つまり、そのリソースに特定のタグがないときだけ、ユーザーにそのリソースのロールが付与される場合、条件はチェックされません。

    たとえば、Data Catalog では、BigQuery データセットの IAM タグ条件を検証できません。employee_type=intern タグを持つデータセットで、インターンに BigQuery データ閲覧者ロールを付与する条件付き IAM ポリシーがあるとします。これは正のタグ条件であるため、そのデータセットに employee_type=intern タグがある場合でも、インターンは Data Catalog で検索してデータセットを表示することはできません。このタグ条件を負の値に変更して、インターンが employee_type=intern タグを持たないデータセットのみを表示できるようにすると、チェックは完全にスキップされ、インターンは BigQuery で通常アクセスできなかったデータセットを表示できるようになります。

次のステップ