Tag Engine を使用して Data Catalog で一括タグを作成する

Last reviewed 2022-11-17 UTC

このガイドでは、Tag Engine を使用して Data Catalog で一括タグを作成する方法について説明します。一括タグとは、類似したタグのコレクションで、1 つのユニットとしてまとめて作成、更新されます。タグを一括で作成すると、組織のデータアセットにタグ付けする際に必要な時間と労力を削減できます。このドキュメントでは、Tag Engine の概要と、アセットに共通のメタデータ属性がある場合にアセットのコレクションにタグを付ける方法について説明します。

Tag Engine は、BigQuery と Cloud Storage のアセットのメタデータ作成に役立つオープンソースツールです。このツールを使用すると、静的メタデータまたは動的メタデータを持つタグを入力できます。Tag Engine は、新しいアセットの自動タグ設定と、基になるデータの変更に伴う既存のタグの更新もサポートしています。

このドキュメントは、組織のデータアセットを正確に記述するメタデータの作成を担当するデータ管理担当者を対象としています。

このドキュメントでは、Tag Engine の初期設定について説明します。これには、いくつかの Terraform スクリプトの実行も含まれます。ここでは、2 つの例を使用して、BigQuery アセットの一括タグ付けについて説明します。どちらの例でも、まず BigQuery で小さなデータセットを作成します。

Tag Engine のアーキテクチャ

Tag Engine は、次の構成でデプロイされます。

Data Catalog および BigQuery と同じプロジェクトにデプロイされ、概念実証や開発環境に適しています。
別の BigQuery プロジェクトで Data Catalog プロジェクトと共有されまるため、本番環境などの高レベル環境に適しています。
独自のプロジェクトにデプロイされることもあり、高レベルの環境に適しています。

Tag Engine のアーキテクチャコンポーネント

上の図は、このドキュメントで使用する共有デプロイパターンを示しています。

目標

データ管理担当者として、Tag Engine を使用して BigQuery アセットの一括メタデータを作成します。
データエンジニアとして、Tag Engine API を使用して BigQuery アセットの一括メタデータを作成します。
Tag Engine の UI またはその API を使用して、静的タグ構成を作成します。
Tag Engine の UI またはその API を使用して、動的タグ構成を作成します。
タグの変更履歴を BigQuery に保存します。
タグの更新を Pub/Sub にリアルタイムで公開して、重要な変更に対してアラートを発します。
Tag Engine のカバレッジレポートでデータエステートを確認し、タグ付けタスクに優先順位を付けます。

費用

始める前に

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Identity and Access Management. App Engine, Firestore API を有効にします。

API を有効にする

Google Cloud Console の [プロジェクトセレクタ] ページで、Google Cloud プロジェクトを選択または作成します。

プロジェクトセレクタに移動

Google Cloud プロジェクトで課金が有効になっていることを確認します。

Identity and Access Management. App Engine, Firestore API を有効にします。

API を有効にする

Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。

Cloud Shell をアクティブにする

Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドラインプロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。

このドキュメントでは、2 つの Google Cloud プロジェクトを紹介します。1 つは Tag Engine の実行用で、もう 1 つは BigQuery にデータを格納するためのものです。これ以降、第 1 の Google Cloud プロジェクトを Tag Engine プロジェクトと呼びます。第 2 の Google Cloud プロジェクトを BigQuery プロジェクトと呼びます。

このドキュメントで作成するリソースを保持する予定がない場合は、既存のプロジェクトを選択するのではなく、2 つのプロジェクトを作成します。

Tag Engine のデプロイと構成

このセクションでは、Google Cloud に Tag Engine をデプロイします。まず、Firestore で Tag Engine データベースを作成し、Google Cloud CLI コマンドを使用して App Engine に Tag Engine アプリケーションをデプロイします。次に、Terraform を使用して Tag Engine を構成します。

Google Cloud に Tag Engine をデプロイする前に、Terraform をダウンロードしてインストールします。Terraform スクリプトは、IAM 権限を付与し、データベースインデックスを作成して、クラウドタスクとスケジューラのエントリを構成します。

Cloud Shell で、必要な環境変数を設定します。

export TAG_ENGINE_PROJECT=PROJECT_ID1
export TAG_ENGINE_REGION=us-central
export TAG_ENGINE_SUB_REGION=us-central1
export BQ_PROJECT=PROJECT_ID2
export BQ_REGION=us-central1
export TAG_ENGINE_SA=${TAG_ENGINE_PROJECT}@appspot.gserviceaccount.com
gcloud config set project ${TAG_ENGINE_PROJECT}

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

PROJECT_ID1 = Tag Engine プロジェクトの ID
PROJECT_ID2 = BigQuery プロジェクトの ID

GitHub Tag Engine コードリポジトリのクローンを作成します。
```
git clone https://github.com/GoogleCloudPlatform/datacatalog-tag-engine.git
```

variables.tfvars ファイルを作成して Terraform 変数を設定します。

cd datacatalog-tag-engine
cat > deploy/variables.tfvars << EOL
tag_engine_project="${TAG_ENGINE_PROJECT}"
bigquery_project="${BQ_PROJECT}"
app_engine_region="${TAG_ENGINE_REGION}"
app_engine_subregion="${TAG_ENGINE_SUB_REGION}"
EOL

Tag Engine 構成ファイル（tagengine.ini）を作成します。

cat > tagengine.ini << EOL\
[DEFAULT]\
TAG_ENGINE_PROJECT = ${TAG_ENGINE_PROJECT}\
QUEUE_REGION = ${TAG_ENGINE_SUB_REGION}\
INJECTOR_QUEUE = tag-engine-injector-queue\
WORK_QUEUE = tag-engine-work-queue\
BIGQUERY_REGION = ${BQ_REGION}\
EOL

Tag Engine 用の App Engine アプリケーションを作成します。

gcloud app create \
  --project=${TAG_ENGINE_PROJECT} \
  --region=${TAG_ENGINE_REGION}

データベースを作成します。

gcloud firestore databases create \
  --project=${TAG_ENGINE_PROJECT} \
  --region=${TAG_ENGINE_REGION}

デフォルトの App Engine サービスアカウントを使用して Tag Engine をデプロイします。
```
gcloud app deploy app.yaml
```
サービスアカウントに Tag Engine プロジェクトに対する編集者のロールが割り当てられていることを確認します。
（省略可）ユーザーが管理するサービスアカウントで Tag Engine をデプロイします。
```
export TAG_ENGINE_SA=SERVICE_ACCOUNT
gcloud beta app deploy --service-account=$TAG_ENGINE_SA app.yaml
```
次の変数を置き換えます。
- SERVICE_ACCOUNT = ユーザー管理のサービスアカウントのメールアドレス。
ユーザー管理のサービスアカウントに、Tag Engine プロジェクトに対する編集者のロールを割り当てます。
ファイアウォールルールを使用して App Engine を保護します。
```
gcloud app firewall-rules create 100 --action ALLOW --source-range
[IP_RANGE]
gcloud app firewall-rules update default --action deny
```
デフォルトでは、App Engine は公共のインターネットからのトラフィックを許可します。App Engine のファイアウォールルールを使用して、ネットワークトラフィックを特定の IP アドレス範囲に制限します。

また、Identity-Aware Proxy（IAP）を使用して IAM でアクセスを管理することもできます。

Tag Engine にアクセスできるように IAP を設定するには、OAuth と IAP アクセスを構成します。
次の Terraform コマンドを実行します。プロンプトが表示されたら、「yes」と入力します。
```
cd deploy
terraform init
terraform apply -var-file variables.tfvars
```
ブラウザで Tag Engine を起動します。
```
gcloud app browse
```

Tag Engine ブラウザインターフェースは、主にデータ管理担当者が一括メタデータタグを作成する場合に使用します。すべてのメタデータタグを作成するために、Tag Engine はタグ構成を使用します。

サンプルデータセットを作成する

このシナリオでは、両方の例で使用されているサンプルデータセットに 3 つのテーブルがあります。このテーブルには、オースティン、ニューヨーク、サンフランシスコの各都市の非緊急の地方自治体サービス 311 の電話番号から公開されているサービスリクエストレコードが保存されています。テーブルは us リージョンにあり、us-central1 リージョンからクエリを実行します。これを行うには、Cloud Storage にエクスポートしてから、BigQuery の正しいリージョンにインポートします。

Cloud Shell で、Cloud Storage の us-central1 リージョンにバケットを作成します。
```
export BUCKET=cities-311
gsutil mb -l ${BQ_REGION} gs://${BUCKET}
```

3 つの 311_service_requests テーブルを Cloud Storage バケットにエクスポートします。

bq extract --destination_format=AVRO \
  bigquery-public-data:austin_311.311_service_requests \
  gs://${BUCKET}/austin/311_service_requests*.avro

bq extract --destination_format=AVRO \
  bigquery-public-data:new_york_311.311_service_requests \
  gs://${BUCKET}/new_york/311_service_requests*.avro

bq extract --destination_format=AVRO \
  bigquery-public-data:san_francisco_311.311_service_requests \
  gs://${BUCKET}/san_francisco/311_service_requests*.avro

Cloud Shell で、サンプルデータセットを作成します。
```
bq --location=${BQ_REGION} mk --dataset ${BQ_PROJECT}:cities_311
```

BigQuery にファイルを読み込む

 bq load --source_format=AVRO ${BQ_PROJECT}:cities_311.austin_311_service_requests \
   gs://${BUCKET}/austin/*.avro

 bq load --source_format=AVRO ${BQ_PROJECT}:cities_311.new_york_311_service_requests \
   gs://${BUCKET}/new_york/*.avro

 bq load --source_format=AVRO ${BQ_PROJECT}:cities_311.san_francisco_311_service_requests \
   gs://${BUCKET}/san_francisco/*.avro
 ```

Cloud Storage から cities 311 のファイルとバケットを削除します。
```
gsutil -m rm -r gs://${BUCKET}
```

Data Catalog タグテンプレートを作成する

Tag Engine でタグ構成を作成する前に、1 つ以上の Data Catalog タグテンプレートを作成する必要があります。タグテンプレートは、同じタイプの 1 つ以上のタグのスキーマを定義する Data Catalog のコンセプトです。スキーマは、フィールド名、そのデータ型、テンプレート内の順序のコレクションを指定します。すべての Data Catalog タグは、タグテンプレートからインスタンス化されます。

主要なパフォーマンス指標を使用して各 311 サービスリクエストテーブルにアノテーションを付けるには、タグテンプレートを作成します。

Cloud Shell で、GitHub datacatalog-templates.git リポジトリのクローンを作成し、datacatalog-templates フォルダに変更します。
```
git clone https://github.com/GoogleCloudPlatform/datacatalog-templates.git
cd datacatalog-templates
```
仮想環境を作成して有効にし、Python の依存関係をインストールします。
```
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

cities_311 タグテンプレートを作成します。

python create_template.py $TAG_ENGINE_PROJECT $TAG_ENGINE_SUB_REGION \
  cities_311.yaml

create_template.py スクリプトは、cities_311.yaml ファイルの内容に基づいてタグテンプレートを作成します。cities_311 タグテンプレートには 11 個のフィールドがあり、そのうちの 2 個は必須です。このタグテンプレートからタグを作成する際は、両方の必須フィールドを指定する必要があります。

フィールド名	フィールドタイプ	必須項目です
avg_daily_total_requests	double	false
avg_daily_open_requests	double	false
avg_daily_closed_requests	double	false
avg_daily_unknown_requests	double	false
sum_total_requests	double	true
unique_total_requests	double	false
closed_total_requests	double	false
open_total_requests	double	false
unknown_total_requests	double	false
unique_total_complaints	double	false
tag_snapshot_time	datetime	true

Google Cloud コンソールで Data Catalog を開き、Cities 311 Service Requests タグテンプレートを表示します。次のスクリーンショットのようになります。

data_governance タグテンプレートを作成します。

python create_template.py ${TAG_ENGINE_PROJECT} ${TAG_ENGINE_SUB_REGION} \
    data_governance.yaml

data_governance テンプレートにも 11 個のフィールドがあり、そのうちの 2 個は必須です。このテンプレートからタグを作成するときに、両方の必須フィールドを指定する必要があります。

フィールド名	種類	必須
data_domain	`enum`	true
broad_data_category	`enum`	true
environment	`enum`	false
data_origin	`enum`	false
data_creation	`datetime`	false
data_ownership	`string`	false
data_asset_owner	`string`	false
data_asset_expert	`string`	false
data_confidentiality	`enum`	false
data_retention	`enum`	false
data_asset_documentation	`string`	false

Google Cloud コンソールで Data Catalog を開き、data_governance タグテンプレートを表示します。次のスクリーンショットのようになります。

Tag Engine の設定

Tag Engine では、デフォルトのタグテンプレートを保存しておくこともできます。各タグのコピーを BigQuery と Pub/Sub に保存することもできます。このセクションでは、これらの各トピックについて詳しく説明します。これらのオプションを設定しなくてもタグ付けを開始できますが、それらのタグを BigQuery にコピーすることや、Pub/Sub に公開することはできません。これらのオプションをスキップする場合は、タグ付けの概要セクションに直接移動してください。

デフォルトのタグテンプレートを保存する

Tag Engine では、タグを作成または編集するたびにタグテンプレート ID、プロジェクト ID、地域を入力しなくても済むように、デフォルトのタグテンプレートを保存できます。

デフォルトのタグテンプレートを設定する手順は次のとおりです。

Tag Engine のホームページで、[Set Default Tag Template] リンクをクリックします。
次の詳細情報を入力します。
- テンプレート ID: cities_311
- テンプレートのプロジェクト: PROJECT_ID
- テンプレートのリージョン: us-central1
PROJECT_ID は、Tag Engine プロジェクトの ID に置き換えます。
[設定を保存] をクリックします。

ホームページのパラメータに、デフォルトのタグテンプレートの詳細が事前入力されるようになりました。

タグ履歴のオプションを選択する

タグ履歴のオプションを使用すると、Tag Engine が作成するすべてのタグのコピーを BigQuery テーブルに保存できます。これにより、すべてのタグの変更履歴を保持できます。すべてのタグは、BigQuery に新しいテーブルレコードとして書き込まれ、1 つのタグテンプレートのすべてのタグ値が同じテーブルに格納されます。テーブルスキーマには、タグの作成時間、アセット名、タグテンプレートのすべてのフィールドが含まれます。cities_311 テンプレートのタグ履歴テーブルは、次のフィールドを使用して作成されます。

フィールド名	フィールドタイプ	説明
event_time	`datetime`	タグ付けオペレーションのタイムスタンプ
asset_name	`string`	BigQuery のアセット名（例: `warehouse-337221/dataset/cities_311/table/new_york_311_service_requests`）
avg_daily_total_requests	`numeric`	`avg_daily_total_requests` フィールドの値
avg_daily_open_requests	`numeric`	`avg_daily_open_requests` フィールドの値
avg_daily_closed_requests	`numeric`	`avg_daily_closed_requests` フィールドの値
avg_daily_unknown_requests	`numeric`	`avg_daily_unknown_requests` フィールドの値
sum_total_requests	`numeric`	`sum_total_requests` フィールドの値
unique_total_requests	`numeric`	`unique_total_requests` フィールドの値
closed_total_requests	`numeric`	`closed_total_requests` フィールドの値
open_total_requests	`numeric`	`open_total_requests` フィールドの値
unknown_total_requests	`numeric`	`unknown_total_requests` フィールドの値
unique_total_complaints	`numeric`	`unique_total_complaints` フィールドの値
tag_snapshot_time	`datetime`	`tag_snapshot_time` フィールドの値

このタグ履歴テーブルの名前は tag_history.cities_311 です。タグ履歴テーブルを保存するデータセットは、tag_history で識別されます。

タグ履歴機能を有効にするには、タグ履歴テーブルを保存する BigQuery データセットを作成します。
```
bq mk --project_id ${BQ_PROJECT} tag_history
```

Tag Engine サービスアカウントに、データセットに対する編集権限を付与します。

 bq query --nouse_legacy_sql \
"GRANT \`roles/bigquery.dataEditor\` ON SCHEMA \`${BQ_PROJECT}.tag_history\`
TO 'serviceAccount:${TAG_ENGINE_PROJECT}@appspot.gserviceaccount.com'"

Tag Engine のホームページで、[Turn on/off Tag History] をクリックします。次の詳細情報を入力します。
- Enable Tag History: オン
- BigQuery プロジェクト ID: PROJECT_ID
- BigQuery リージョン: us-central1
- BigQuery データセット: tag_history
次の変数を置き換えます。 - PROJECT_ID = BigQuery プロジェクトの ID。
[設定を保存] をクリックします。

注: Tag Engine は、タグ履歴テーブルをホストするための BigQuery データセットを作成しません。タグ履歴を有効にする前に、Tag Engine の外部で作成する必要があります。
（省略可）この機能をオフにするには、[タグ履歴の設定] ページに移動し、[Enable tag history: オフ] を選択して、変更内容を保存します。

タグストリームオプションを選択する

タグストリームオプションを使用すると、Tag Engine は、作成したすべてのタグのコピーを Pub/Sub トピックにパブリッシュします。この操作により、タグ値の変更を監視して対応できます。

Cloud Shell で Pub/Sub トピックを作成します。

gcloud pubsub topics create tag-stream \
  --project=${BQ_PROJECT}

Pub/Sub トピックにサブスクリプションを作成します。

gcloud pubsub subscriptions create tag-stream-sub \
  --topic=tag-stream \
  --topic-project=${BQ_PROJECT}

Tag Engine サービスアカウントに Pub/Sub トピックに関する権限を付与します。

gcloud pubsub topics add-iam-policy-binding tag-stream \
  --project=${BQ_PROJECT} \
  --member="serviceAccount:${TAG_ENGINE_PROJECT}@appspot.gserviceaccount.com" \
   --role="roles/editor"

タグストリームのホームページで、[Turn on/off Tag Stream] リンクをクリックします。次の詳細情報を入力します。
- Enable Tag Stream: オン
- Pub/Sub プロジェクト ID: PROJECT_ID
- Pub/Sub トピック: tag-stream
PROJECT_ID は、BigQuery プロジェクトの ID に置き換えます。
[設定を保存] をクリックします。
（省略可）タグストリームをオフにするには、[Enable Tag Stream] メニューから [オフ] を選択し、変更を保存します。

タグ付けの概要

Tag Engine には、主に動的と静的の 2 つのタグ構成があります。

動的構成では、タグテンプレートのフィールドごとにクエリ式が割り当てられます。クエリ式は、いくつかの特殊な変数を使用して SQL で提供されます。動的構成には、タグを更新するタイミングと方法に関する情報も含まれます。動的構成を使用して、BigQuery から取得したメタデータ属性（オペレーションメタデータなど）をタグに設定します。使用できる動的構成には、BigQuery のテーブルとビューにタグを付ける動的テーブル構成と、BigQuery のフィールドにタグを付ける動的列構成の 2 種類があります。

静的構成では、タグ内の各タグテンプレートフィールドに定数値が割り当てられます。静的構成を使用して、ほとんど変更しない記述的なメタデータ（データの所有権やデータドメイン情報など）でアセットにタグを付けます。アセットは、BigQuery データセット、テーブル、ビュー、または Cloud Storage バケット、フォルダ、ファイルのいずれかです。この構成では、静的アセット構成のみを使用できます。

Tag Engine では、ウェブインターフェースまたは API を使用して構成を作成できます。データ管理担当者は通常、ウェブインターフェースを使用することをおすすめします。ウェブインターフェースを使用すると、データ管理担当者がデータパイプラインを作成する必要がなくなります。また、ウェブインターフェースでは、SQL を使用して新しいタグを開発するための自律性とアジリティがもたらされます。データエンジニアは通常、特に本番環境で API を使用することをおすすめします。API を使用すると、タグ付けタスクをデータパイプラインに統合して、タグの更新のタイミングをより細かく管理できます。

構成を作成するときは、ユースケースとチームに適した方法（ウェブインターフェースまたは API）を選択します。以下のセクションでは、両方の方法について、まずはウェブインターフェースの使用方法から詳しく説明します。

動的タグ構成を作成する

動的構成では、Data Catalog タグのコレクションが生成されます。各タグは、一意のタグテンプレートと BigQuery リソースの組み合わせに関連付けられます。動的と呼ばれるのは、タグの内容がクエリ式の結果から設定されるためです。

前述のように、動的構成ではテーブルレベルのタグまたは列レベルのタグのいずれかが生成されますが、両方は生成されません。テーブルレベルのタグを作成するには、動的テーブルの構成タイプを選択します。列レベルのタグを作成するには、動的列の構成タイプを使用する必要があります。

選択するタイプに関係なく、動的構成には次の 3 つのセクションが含まれます。

クエリ式: 1 つ以上のタグテンプレートフィールドの値を生成する方法を指定します。
URI 式: 1 つ以上の BigQuery リソース（テーブル、ビュー、データセット）へのパスを指定します。
スケジュール設定: 現在の構成に関連付けられている Data Catalog タグを更新する頻度を指定します。

タグテンプレートの必須フィールド（sum_total_requests、tag_snapshot_time など）は自動的に選択されます。各タグテンプレートのフィールドの横に、クエリ式を入力します。各フィールドに想定される型は括弧内に示されています。BigQuery では、クエリ式は有効な SELECT ステートメントになっている必要があります。SELECT 句は必須です。FROM 句と WHERE 句は省略可能ですが、頻繁に使用されます。SELECT ステートメントの他の句（JOIN や GROUP BY など）も使用できます。

SELECT ステートメントのさまざまな句内で、クエリ式は $table や $column などのいくつかの変数を参照できます。参照可能なすべての変数は次のとおりです。

$project: タグを付ける BigQuery リソースのプロジェクト ID。
$dataset: タグを付ける BigQuery リソースのデータセット名。
$table: タグを付ける BigQuery リソースのテーブル名。クエリ式の FROM 句で使用すると、タグを付けるテーブルへの完全修飾パスに解決されます。例: warehouse-337221.cities_311.austin_311_service_requests。クエリ式の WHERE 句で使用すると、テーブル名（例: austin_311_service_requests）に解決されます。
$column: タグを付ける BigQuery リソースの列名。この変数は、列レベルのタグを作成する場合にのみ使用できます。

クエリ式では、これらの特殊変数を参照するだけでなく、round、cast、extract などの組み込み BigQuery 関数を参照することもできます。

`cities_311` タグテンプレートを使用して動的テーブル構成を作成する

このセクションでは、cities_311 タグテンプレートを使用して動的なテーブル構成を作成します。

タグテンプレートのホームページで、まだ設定していない場合は、タグテンプレート ID、プロジェクト ID、リージョンを入力し、[検索テンプレート] をクリックします。
[タグテンプレートの詳細] ページで、[Create Dynamic Table Tags] をクリックします。

構成のクエリ式セクションが [動的テーブルタグ作成の構成] ページに表示されます。ページ上で、タグテンプレートの必須フィールド（この場合は sum_total_requests と tag_snapshot_time）が自動的に選択されます。

タグテンプレートの必須フィールドが自動的に選択されます（この場合は sum_total_requests と tag_snapshot_time）。
各タグテンプレートフィールドの横のテキストフィールドに、クエリ式を入力します。

クエリ式は、BigQuery 内の有効な SELECT ステートメントになっている必要があります。SELECT 句は必須です。FROM 句と WHERE 句は省略可能ですが、頻繁に使用されます。SELECT ステートメントの他の句（JOIN や GROUP BY など）も使用できます。

各クエリ式は、対応するタグテンプレートのフィールドタイプと互換性のある値を返す必要があります。たとえば、sum_total_requests フィールドに関連付けられた式は、numeric 値を返す必要があります。tag_snapshot_time フィールドに関連付けられた式は、datetime 値を返す必要があります。各フィールドに想定される型がリストされます。

SELECT ステートメントのさまざまな句内で、クエリ式で $table や $column などの特殊な変数を参照できます。参照可能なすべての変数は次のとおりです。
- $project: タグを付ける BigQuery リソースのプロジェクト ID。
- $dataset: タグを付ける BigQuery リソースのデータセット名。
- $table: タグを付ける BigQuery リソースのテーブル名。クエリ式の FROM 句で使用する場合、$table はタグ付けされるテーブルへの完全修飾パスに解決されます。例: warehouse-337221.cities_311.austin_311_service_requests。クエリ式の WHERE 句で使用すると、テーブル名（例: austin_311_service_requests）に解決されます。
- $column: タグを付ける BigQuery リソースの列名。この変数は列レベルのタグでのみ使用でき、この cities_311 の例には適用されません。
クエリ式では、これらの特殊変数を参照するだけでなく、round、cast、extract などの組み込み BigQuery 関数を参照することもできます。

該当するフィールドに次のクエリを入力します。

フィールド名	クエリ式
avg_daily_total_requests	select ifnull(round(avg(daily_requests), 2), 0) from (select date_created, count(*) as daily_requests from (select extract(date from timestamp_micros(created_date)) as date_created from $table) group by date_created)
avg_daily_open_requests	select ifnull(round(avg(daily_requests), 2), 0) from (select date_created, count(*) as daily_requests from (select extract(date from timestamp_micros(created_date)) as date_created from $table where status = 'Open') group by date_created)
avg_daily_closed_requests	select ifnull(round(avg(daily_requests), 2), 0) from (select date_created, count(*) as daily_requests from (select extract(date from timestamp_micros(created_date)) as date_created from $table where status = 'Closed') group by date_created)
avg_daily_unknown_requests	select ifnull(round(avg(daily_requests), 2), 0) from (select date_created, count(*) as daily_requests from (select extract(date from timestamp_micros(created_date)) as date_created from $table where status not in ('Open', 'Closed')) group by date_created)
sum_total_requests	select count(*) from $table
unique_total_requests	select count(distinct unique_key) from $table
closed_total_requests	select count(*) from $table where status = 'Closed'
open_total_requests	select count(*) from $table where status = 'Open'
unknown_total_requests	select count(*) from $table where status not in ('Closed', 'Open')
unique_total_complaints	select count(distinct complaint_type) from $table
tag_snapshot_time	select current_datetime

タグテンプレートのすべてのフィールドを含めるチェックボックスをオンにします。

構成ファイルを完成させる

構成ファイルの次のセクションでは、BigQuery リソースへの URI を記述します。このセクションは、次の 2 つの部分で構成されています。

最初の部分は [含まれているテーブルの URI] です。このフィールドには、BigQuery リソースへの 1 つ以上のパスが含まれます。どのタグ構成にも、含まれるテーブルの URI パスが少なくとも 1 つ必要です。

[Included Tables URIs] フィールドの URI の形式は、bigquery/project/{project}/dataset/{dataset}/{table}/{column} です。

URI の最初の 4 つのコンポーネント（{dataset} 以下）が必要です。残りのコンポーネントは省略可能です。

プロジェクト全体にタグを付けるには、bigquery/project/{project}/*; を使用します。データセット全体にタグを付けるには、bigquery/project/{project}/dataset/{dataset}/* を使用します。データセット名とテーブル名にはワイルドカードを使用できます。たとえば、bigquery/project/warehouse-337221/dataset/cities_311/austin* は cities_311 データセット内のすべてのテーブルとビューと一致し、先頭は austin* という文字列になります。
2 番目の部分は [除外テーブルの URI] フィールドです。このオプションのフィールドを使用すると、1 つ以上の含まれているテーブルの URI パスに一致するリソースを除外できます。[除外テーブルの URI] を使用して、一時テーブルとステージングテーブルがタグ付けされないように除外できます。このフィールドは、[含まれるテーブルの URI] と同じ形式ルールに基づいています。

構成ファイルを完成させるには、次の手順に沿って操作します。

[含まれるテーブルの URI] に、bigquery/project/PROJECT_ID/dataset/cities_311/* を入力します。

PROJECT_ID は、BigQuery プロジェクトの ID に置き換えます。
[除外テーブルの URI] は空白のままにします。
[自動] を選択して、タグの更新頻度をスケジュール設定します。次の更新モードを選択できます。
- 自動: 選択した更新頻度に基づいて、Tag Engine によってタグの更新がトリガーされます。
- オンデマンド: Tag Engine の自動更新を無効にします。更新が他のデータ処理タスクに依存しており、API を介してそれらの更新をトリガーする場合は、オンデマンドを選択します。
（省略可）タグの履歴とタグストリームのオプションを設定します。両方のボックスを選択したままにして、デフォルト値を受け入れます。

これらのオプションは、動的テーブル構成を作成する前にタグ履歴とストリームオプションを有効にした場合にのみ表示されます。タグ履歴オプションを使用すると、新しいタグと更新されたタグのコピーが、この構成から BigQuery テーブルに保存されます。タグストリームオプションは、この構成から新しいタグと更新されたタグのコピーを Pub/Sub トピックにパブリッシュします。タグ履歴レコードは、タグテンプレート別に整理されます。タグストリームメッセージは同じトピックに配置されます。
[Submit Tag Config] をクリックします。

Tag Engine が動的テーブル構成を処理していることを示す確認ページが表示されます。
構成ページのステータスを更新するには、表示されたリンクをクリックします。

構成のステータスが表示された [構成を表示] ページを表示するには、[こちら] リンクをクリックします。

次の構成ステータスがあります。
- 保留中: 構成が送信され、一括タグジョブを作成しています。
- 実行中: 一括タグジョブが実行中です。完了率も表示されます。
- 有効: 一括タグジョブは完了しており、構成は有効です。
- エラー: 一括タグジョブで 1 つ以上のエラーが発生しました。詳細については、App Engine のログを確認してください。
cities_311 構成ファイルのステータスが有効に変わったら、Data Catalog UI を開きます。
Data Catalog UI で、[タグテンプレート] ページをクリックし、cities_311 テンプレートを選択します。
テンプレートの詳細ページで、[search for entries matching the template] をクリックします。

検索結果には 3 つのエントリが含まれます（都市ごとに 1 つ）。
3 つのエントリのいずれかをクリックすると、タグテンプレートのフィールドとクエリ式の結果を含む cities_311 タグが表示されます。このデータセットは毎日更新されます。

スケジュール設定されたタグの更新を確認する

動的構成によって生成されたすべてのタグが Tag Engine によって自動的に更新されていることを確認する方法は 3 つあります。

第 1 の方法は、タグの最終更新日時を記録するフィールドをタグテンプレートに追加する方法です。cities_311 の例では、tag_snapshot_time フィールドが select current_datetime に構成されており、この関数を提供しています。動的構成を作成したら、完全な更新サイクル（cities_311 の例では 24 時間）を 1 回待ってから、Data Catalog でタグを確認します。tag_snapshot_time フィールドの値が 1 日増加します。この値が 24 時間以上遅れている場合、更新は意図したとおりに機能していません。詳細については、App Engine のログを確認してください。

第 2 の方法は、BigQuery のタグ履歴テーブルに対してクエリを実行することです。この方法を使用するには、構成でタグ履歴オプションを有効にする必要があります。次のスクリーンショットは、cities_311 タグの最終更新が 2022 年 2 月 20 日であることを示しています。

タグ履歴の結果が表示された BigQuery のクエリエディタページ。

第 3 の方法は、Firestore で構成ドキュメントを検索して、Tag Engine 構成ストアを調査する方法です。Tag Engine 構成ストアを調べる手順は次のとおりです。

Firestore を開き、dynamic_table_configs コレクションで構成ドキュメントを探します。

コレクションに多数のドキュメントが含まれている場合は、config_status = ACTIVE または config_type = DYNAMIC_TABLE_TAG でドキュメントをフィルタリングできます。
構成を含むドキュメントで、スケジュール構成のセクションを見つけて、次のフィールドを探します。
next_run: Tag Engine がタグを更新できる最も早い時間を示します
scheduling_status: 構成を更新する準備ができているかどうかを示します
version: 発生した更新の数を示します
アップデートを確実に実行するために、scheduling_status フィールドを Ready に設定し、next_run フィールドがタイムスタンプであることを確認します。

静的タグを作成する

動的タグ構成とは異なり、静的タグの構成は、データアセットの所有者やデータアセットのドメインなど、ほとんど変更されないメタデータ属性を入力するためのものです。動的構成と同様に、静的タグ構成では複数の Data Catalog タグが生成されます。各タグは、データセット、テーブル、ビュー、バケット、フォルダ、ファイルなど、一意の BigQuery または Cloud Storage リソースにリンクされます。動的構成とは異なり、静的構成では、タグに含まれる各テンプレートフィールドに定数値が割り当てられます。したがって、静的タグ構成によって生成されたすべてのタグには、同一のメタデータ値が含まれます。3 つの cities_311 テーブルにタグを付ける静的構成を作成するには、次の手順を完了します。

Tag Engine のランディングページで、次の data_governance タグテンプレートの詳細を入力します。
- タグテンプレート ID: data_governance
- Google Cloud プロジェクト ID: PROJECT_ID
- Google Cloud リージョン: us-central1
PROJECT_ID は、Tag Engine プロジェクトの ID に置き換えます。
[テンプレートを検索] をクリックします。[data_governance タグテンプレートの詳細] ページが表示されます。
[data_governance タグテンプレートの詳細] ページで、[Create Static Asset Tags] をクリックします。
[Config for creating static asset tags] ページで、[Template Field Values] セクションに次の詳細を入力します。
- data_domain（enum）: GOVERNMENT
- broad_data_category（enum）: CONTENT
- environment（enum）: DEV
- data_origin（enum）: OPEN_DATA
- data_creation（datetime）: 2022-11-08 20:40:50
- data_ownership（enum）: PUBLIC_DOMAIN
- data_asset_owner（string）: Emily Doe
- data_asset_expert（string）: John Smith
- data_confidentiality（enum）: PUBLIC
- data_retention（enum）: 30_DAYS
- data_asset_documentation（string）: https://support.datasf.org/help/311-case-data-faq
注: data_creation フィールドの値はデフォルトで現在の日時になります。
ページの [BigQuery] または [Google Cloud Storage アセット] セクションで、次の値を入力します。
- 含まれるアセットの URI: bigquery/project/PROJECT_ID/dataset/cities_311/*
PROJECT_ID は、BigQuery プロジェクトの ID に置き換えます。
- 除外アセット URI: このフィールドは空白のままにします。除外するテーブルはありません。
[オプションを更新] セクションで、次の値を入力します。
- 更新モード: AUTO
- 更新頻度: 24 hours
注: 静的構成の更新オプションは、動的構成とはセマンティクスが異なります。静的構成の更新モードが AUTO の場合、Tag Engine は、指定された更新頻度で、含まれるアセットの URI に一致する新しいアセットにタグを付けます。更新モードを ON-DEMAND にすると、都合のよい時間に API から更新をトリガーします。いずれの場合も、この構成ですでにタグ付けされているアセットが、更新中に再度タグ付けされることはありません。
[タグ履歴] と [タグストリーム] の両方のチェックボックスをオンのままにして、デフォルト値を受け入れます。
[タグ構成を送信] をクリックして、静的タグ構成を送信します。確認ページが表示され、リクエストが処理中であることを示します。

構成のステータスを表示するには、[こちら] リンクをクリックします。タグ付けが完了すると、数秒以内にステータスが ACTIVE に変わります。ジョブが大きいほど時間がかかります。ジョブの初期化と実行中は、ステータスは PENDING と PROCESSING のように表示されます。
Data Catalog UI を開いて、生成されたタグを確認します。
tag:data_governance を使用してエントリを検索します。

結果に 3 つの cities_311 テーブルが表示されます。各エントリには、静的構成で割り当てたフィールド名と値を含む data_governance タグが含まれます。結果は次のスクリーンショットのようになります。

API から構成を作成してタグの更新をトリガーする

Tag Engine には、静的および動的な構成の作成や、タグの更新をトリガーするためのさまざまな API メソッドが用意されています。コードリポジトリの /examples フォルダには、各メソッドのさまざまな例があります。static_asset_configs の例は data_governance タグテンプレートに基づいており、dynamic_table_configs の例は cities_311 タグテンプレートに基づいています。

static_asset_tags: JSON 形式の構成リクエストに基づいて静的アセット構成を作成します。ジョブ ID を返します。リクエストの例。
dynamic_table_tags: JSON 形式の構成リクエストに基づいて動的テーブル構成を作成します。ジョブ ID を返します。リクエストの例。
dynamic_column_tags: JSON 形式の構成リクエストに基づいて動的な列構成を作成します。ジョブ ID を返します。リクエストの例。
ondemand_updates: 更新リクエストをトリガーします。このリクエストにより、タグの内容が更新されるか（動的構成）、新しいアセットのタグが作成されます（静的構成）。refresh_mode を ON_DEMAND に設定した静的構成または動的構成が必要です。リクエストの形式は JSON です。ジョブ ID を返します。リクエストの例。
get_job_status: 作成ジョブまたは更新ジョブについて、次のステータスを返します。ジョブ ID が必要です。
- job_status
- success
- task_count
- tasks_completed
- tasks_failed
- tasks_ran

動的テーブル構成を作成する

次の手順では、cities_311 タグテンプレート用に提供されている構成リクエストのいずれかを使用して、dynamic_table_tags メソッドを呼び出す方法を示します。

Cloud Shell で、examples/dynamic_table_configs/dynamic_table_create_ondemand.json ファイルを編集します。template_project、template_region、included_tables_uris フィールドの値を、Tag Engine プロジェクト、Tag Engine リージョン、BigQuery プロジェクトに置き換えます。
API 呼び出しを行って動的タグの構成を作成します。
```
export TAG_ENGINE_URL=https://${TAG_ENGINE_PROJECT}.uc.r.appspot.com
RESPONSE_JSON=$(curl -X POST ${TAG_ENGINE_URL}/dynamic_create -d @examples/dynamic_table_configs/dynamic_table_create_ondemand.json)
JOB_ID=$(echo ${RESPONSE_JSON} | jq -r ".job_uuid")
echo "Job ID: ${JOB_ID}"
```
リクエストが成功すると、API メソッドはジョブ ID を返します。リクエストが成功しなかった場合は、出力にエラーの詳細が示されます。gcloud app logs tail -s default を実行すると、App Engine のログでも詳細を確認できます。
ジョブのステータスをリクエストするには、前の手順で取得したジョブ ID を使用します。
```
curl -X POST ${TAG_ENGINE_URL}/get_job_status \
-d "{\"job_uuid\":\"${JOB_ID}\"}"
```
出力は次のようになります。
```
{"job_status":"COMPLETED","success":true,"task_count":3,"tasks_completed":3,"tasks_failed":0,"tasks_ran":3}
```
ジョブが終了すると、ステータス COMPLETED が返されます。結果のタグを表示するには、Data Catalog に移動します。

API を使用してタグの更新をトリガーする

この構成はオンデマンドスケジューリング（refresh_mode: ON_DEMAND）で作成したため、API を使用してタグの更新をトリガーすることもできます。オンデマンドスケジューリングは、タグの更新スケジュールが異なる場合に役立ちます。異なる場合は、自動スケジューリングモードを使用しないでください。代わりに、オンデマンドスケジューリングを使用するように構成し、ondemand_updates メソッドを使用してタグの更新をトリガーする必要があります。

動的テーブルの更新を作成する

examples/dynamic_table_configs/dynamic_table_update_ondemand.json ファイルを編集します。次の値を置き換えます。
- template_project: Tag Engine のプロジェクト ID
- template_region: us-central1
- included_tables_uris: BigQuery プロジェクトの URI

次のコマンドを実行します。

RESPONSE_JSON=$(curl -X POST ${TAG_ENGINE_URL}/ondemand_updates -d @examples/dynamic_table_configs/dynamic_table_update_ondemand.json)
JOB_ID=$(echo ${RESPONSE_JSON} | jq -r ".job_uuid")
echo "Job ID: ${JOB_ID}"

リクエストが成功すると、このメソッドはジョブ ID を返します。

ジョブのステータスを取得するには、get_job_status メソッドを呼び出します。
```
curl -X POST ${TAG_ENGINE_URL}/get_job_status \
-d "{\"job_uuid\":\"${JOB_ID}\"}"
```

静的タグの構成を作成して更新をトリガーする

Tag Engine には、静的アセット構成を作成するための API メソッド static_asset_tags が用意されています。このメソッドは、JSON オブジェクトを入力として受け取り、ジョブ ID を返します。次の手順では、データガバナンスタグテンプレートを使用して静的構成を作成する方法を示します。

Cloud Shell でファイル examples/static_asset_configs/static_asset_create_ondemand_bq.json を編集します。次の値を置き換えます。
- template_project: Tag Engine のプロジェクト ID
- template_region: us-central1
- included_assets_uris: BigQuery プロジェクトの URI

API 呼び出しを行って静的構成を作成します。

RESPONSE_JSON=$(curl -X POST ${TAG_ENGINE_URL}/static_asset_tags -d @examples/static_asset_configs/static_asset_create_ondemand_bq.json)
JOB_ID=$(echo ${RESPONSE_JSON} | jq -r ".job_uuid")
echo "Job ID: ${JOB_ID}"

リクエストが成功すると、API メソッドはジョブ ID を返します。リクエストが成功しなかった場合は、出力にエラーの詳細が示されます。

（省略可）App Engine のログで詳細を確認するには、次のコマンドを実行します。
```
gcloud app logs tail -s default
```

ジョブのステータスをリクエストするには、前の手順で取得したジョブ ID を使用します。

curl -X POST ${TAG_ENGINE_URL}/get_job_status \
-d "{\"job_uuid\":\"${JOB_ID}\"}"

出力は次のようになります。

  {"job_status":"RUNNING","success":true,"task_count":3,"tasks_completed":0,"tasks_failed":0,"tasks_ran":0}

負荷テストを実行する

Tag Engine には、一括タグ付け機能の負荷テストを実施するためのさまざまなユーティリティと例が用意されています。load_testing フォルダには、BigQuery テーブルのクローンを作成して読み込む Python スクリプトが含まれています。このフォルダの *_standalone.py スクリプトは単一のマシンで実行され、順番に BigQuery テーブルを作成します。同じフォルダ内の *_distributed.py スクリプトが、Cloud Tasks と Cloud Functions を使用して BigQuery テーブルを並行して作成します。BigQuery データセット内のタグ付けされたアセットの数を検証する check_tags.py スクリプトもあります。

examples ディレクトリには、さまざまなバッチサイズ（静的タイプと動的タイプの両方）用の構成リクエストファイルが JSON で記述されています。構成は、このガイドで使用される cities_311 および data_governance タグテンプレートに基づいています。

次の表に、静的構成の例と、その平均実行時間の概要を示します。

バッチサイズ	構成ファイル	ランタイム（HH:MM）
タグの書き込み 500 回	静的作成 500 回	00:01
タグの書き込み 5,000 回	静的作成 5,000 回	00:06
タグの書き込み 50,000 回	静的作成 50,000 回	01:02
タグの書き込み 500,000 回	静的作成 500,000 回	14:17

BigQuery に対してクエリを実行すると追加の処理が必要になるため、動的構成では、通常、同じバッチサイズの静的構成よりもランタイムとコストが高くなります。

カバレッジレポートを作成する

Tag Engine では、データエステート全体の Data Catalog タグをまとめたレポートが提供されます。レポートには、各データアセットのリストとそこにあるタグの数が表示されます。複数のプロジェクトを含むようにレポートを構成できます。また、特定のデータセットやテーブルをプロジェクトから除外するようにレポートを構成することもできます。カバレッジレポートを構成する手順は次のとおりです。

Tag Engine のホームページで、[Configure Coverage Report] をクリックします。

デフォルトでは、プロジェクト内のすべてのデータセットがレポートに含まれます。特定のデータセットとテーブルをレポートから除外する場合は、対応するフィールドで指定します。カバレッジレポートの設定を保存します。
[カバレッジレポートの設定] ページにプロジェクトの詳細を入力し、[保存] をクリックします。
[カバレッジレポート] をクリックします。レポートが変更され、各アセットのタグの数が反映されます。

たとえば、cities_311 テンプレートに動的テーブル構成を作成し、data_governance テンプレートに静的アセット構成を作成した場合、次のスクリーンショットに示すように、3 つの BigQuery テーブルにそれぞれ 2 つのタグが表示されます。

Tag Engine を使用して Data Catalog で一括タグを作成する

Tag Engine のアーキテクチャ

目標

費用

始める前に

Tag Engine のデプロイと構成

サンプル データセットを作成する

Data Catalog タグ テンプレートを作成する

Tag Engine の設定

デフォルトのタグ テンプレートを保存する

タグ履歴のオプションを選択する

タグストリーム オプションを選択する

タグ付けの概要

動的タグ構成を作成する

cities_311 タグ テンプレートを使用して動的テーブル構成を作成する

構成ファイルを完成させる

スケジュール設定されたタグの更新を確認する

静的タグを作成する

API から構成を作成してタグの更新をトリガーする

動的テーブル構成を作成する

API を使用してタグの更新をトリガーする

動的テーブルの更新を作成する

静的タグの構成を作成して更新をトリガーする

負荷テストを実行する

カバレッジ レポートを作成する

次のステップ

サンプルデータセットを作成する

Data Catalog タグテンプレートを作成する

デフォルトのタグテンプレートを保存する

タグストリームオプションを選択する

`cities_311` タグテンプレートを使用して動的テーブル構成を作成する

カバレッジレポートを作成する