このページは Cloud Translation API によって翻訳されました。

HDFS データレイクからテーブルを移行する

このドキュメントでは、Apache Hadoop Distributed File System（HDFS）データレイクテーブルを Google Cloudに移行する方法について説明します。

BigQuery Data Transfer Service の HDFS データレイク移行コネクタを使用すると、オンプレミス環境とクラウド環境の両方で、さまざまな Hadoop ディストリビューションから Hive テーブルと Iceberg テーブルを Google Cloudに移行できます。

HDFS データレイクコネクタを使用すると、Cloud Storage をファイルの基盤となるストレージとして使用しながら、HDFS データレイクテーブルを Dataproc Metastore と BigLake Metastore の両方に登録できます。

次の図は、Hadoop クラスタからのテーブル移行プロセスの概要を示しています。

Hive データレイクから BigQuery へのテーブル移行の概要。

制限事項

HDFS データレイクの転送には、次の制限事項があります。

Iceberg テーブルを移行するには、オープンソースエンジン（Spark や Flink など）の書き込みアクセスを許可し、BigQuery の読み取りアクセスを許可するために、BigLake Metastore にテーブルを登録する必要があります。
Hive テーブルを移行するには、テーブルを Dataproc Metastore に登録して、オープンソースエンジンの書き込みアクセスを許可し、BigQuery の読み取りアクセスを許可する必要があります。
HDFS データレイクテーブルを BigQuery に移行するには、bq コマンドラインツールを使用する必要があります。

始める前に

HDFS データレイク転送のスケジュールを設定する前に、次の操作を行う必要があります。

移行するファイル用の Cloud Storage バケットを作成する

移行するデータレイクファイルの移行先となる Cloud Storage バケットを作成します。このドキュメントでは、このバケットを MIGRATION_BUCKET と呼びます。

Apache Hive のメタデータファイルを生成する

dwh-migration-dumper ツールを実行して、Apache Hive のメタデータを抽出します。このツールは、hive-dumper-output.zip という名前のファイルを Cloud Storage バケット（このドキュメントでは DUMPER_BUCKET と呼びます）に生成します。

API を有効にする

Google Cloud プロジェクトで次の API を有効にします。

Data Transfer API
Storage Transfer API

Data Transfer API を有効にすると、サービスエージェントが作成されます。

権限を構成する

サービスアカウントを作成し、BigQuery 管理者ロール（roles/bigquery.admin）を付与します。このサービスアカウントは、転送構成の作成に使用されます。
Data Transfer API を有効にすると、サービスエージェント（P4SA）が作成されます。次のロールを付与します。
- roles/metastore.metadataOwner
- roles/storagetransfer.admin
- roles/serviceusage.serviceUsageConsumer
- roles/storage.objectViewer
  - BigLake Iceberg テーブルのメタデータを移行する場合は、roles/storage.objectViewer ではなく roles/storage.objectAdmin ロールと roles/bigquery.admin ロールを付与します。

次のコマンドを使用して、サービスエージェントに roles/iam.serviceAccountTokenCreator ロールを付与します。

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-bigquerydatatransfer.iam.gserviceaccount.com --role roles/iam.serviceAccountTokenCreator

Storage Transfer エージェントを構成する

HDFS データレイクの転送に必要な Storage Transfer エージェントを設定するには、次の操作を行います。

Hadoop クラスタで Storage Transfer エージェントを実行するように権限を構成します。
オンプレミスエージェントマシンに Docker をインストールします。
Google Cloud プロジェクトに Storage Transfer Service エージェントプールを作成します。
オンプレミスエージェントマシンにエージェントをインストールします。

HDFS データレイク転送のスケジュールを設定する

HDFS データレイク転送のスケジュールを設定するには、以下のように bq mk コマンドを入力して、転送作成フラグ --transfer_config を指定します。

  bq mk --transfer_config
  --data_source=hadoop
  --display_name='TRANSFER_NAME'
  --service_account_name='SERVICE_ACCOUNT'
  --project_id='PROJECT_ID'
  --location='REGION'
  --params='{"table_name_patterns":"LIST_OF_TABLES",
    "agent_pool_name":"AGENT_POOL_NAME",
    "table_metadata_path":"gs://DUMPER_BUCKET/hive-dumper-output.zip",
    "target_gcs_file_path":"gs://MIGRATION_BUCKET",
    "destination_dataproc_metastore":"DATAPROC_METASTORE",
    "destination_bigquery_dataset":"BIGLAKE_METASTORE",
    "translation_output_gcs_path":"gs://TRANSLATION_OUTPUT_BUCKET/metadata/config/default_database/"
    }'

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

TRANSFER_NAME: 転送構成の表示名。転送名には、後で修正が必要になった場合に識別できる任意の名前を使用できます。
SERVICE_ACCOUNT: 転送の認証に使用されるサービスアカウント名。サービスアカウントは、転送の作成に使用した project_id が所有している必要があります。また、必要な権限がすべて付与されている必要があります。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。--project_id で特定のプロジェクトを指定しない場合は、デフォルトのプロジェクトが使用されます。
REGION: この転送構成のロケーション。
LIST_OF_TABLES: 転送するエンティティのリスト。階層型の命名規則（database.table）を使用します。このフィールドでは、RE2 正規表現を使用してテーブルを指定できます。次に例を示します。
- db1..*: データベース内のすべてのテーブルを指定します。
- db1.table1;db2.table2: テーブルのリストを指定します。
AGENT_POOL_NAME: エージェントの作成に使用されるエージェントプールの名前。
DUMPER_BUCKET: hive-dumper-output.zip ファイルを含む Cloud Storage バケット。
MIGRATION_BUCKET: すべての基盤となるファイルが読み込まれる宛先 GCS パス。
メタデータは、Dataproc Metastore または BigLake Metastore に移行できます。基盤となるデータは Cloud Storage に保存されます。宛先は、次のいずれかのパラメータを使用して指定できます。
- メタデータを Dataproc Metastore に転送するには、destination_dataproc_metastore パラメータを使用して、DATAPROC_METASTORE で Metastore の URL を指定します。
- 代わりにメタデータを BigLake metastore に転送するには、destination_bigquery_dataset パラメータを使用して、BIGLAKE_METASTORE で BigQuery データセットを指定します。
TRANSLATION_OUTPUT_BUCKET: （省略可）変換出力用の Cloud Storage バケットを指定します。詳細については、翻訳出力の使用をご覧ください。

このコマンドを実行して転送構成を作成し、HDFS データレイク転送を開始します。転送は、デフォルトで 24 時間ごとに実行するようにスケジュール設定されていますが、転送スケジュールのオプションで構成できます。

転送が完了すると、Hadoop クラスタのテーブルが MIGRATION_BUCKET に移行されます。

データの取り込みオプション

以降のセクションでは、HDFS データレイク転送の構成方法について詳しく説明します。

増分転送

転送構成が定期的なスケジュールで設定されている場合、後続の転送が実行されるたびに、移行元テーブルに加えられた最新の更新を反映するように Google Cloud のテーブルが更新されます。たとえば、スキーマ変更に伴うすべての挿入、削除、更新オペレーションが転送のたびに Google Cloud に反映されます。

転送のスケジュール設定オプション

デフォルトでは、転送は 24 時間ごとに実行されるようにスケジュール設定されています。転送の実行頻度を構成するには、転送構成に --schedule フラグを追加し、schedule 構文を使用して転送スケジュールを指定します。HDFS データレイク転送では、転送の実行間隔を 24 時間以上にする必要があります。

1 回限りの転送の場合は、転送構成に end_time フラグを追加して、転送を 1 回だけ実行できます。

変換出力を構成する

移行されたテーブルごとに、一意の Cloud Storage パスとデータベースを構成できます。これを行うには、次の手順で、転送構成で使用できるテーブルマッピング YAML ファイルを生成します。

DUMPER_BUCKET に、次の内容を含む構成 YAML ファイル（接尾辞 config.yaml）を作成します。
```
    type: object_rewriter
    relation:
    - match:
        relationRegex: ".*"
      external:
        location_expression: "'gs://MIGRATION_BUCKET/' + table.schema + '/' + table.name"
```
- MIGRATION_BUCKET は、移行されたテーブルファイルの宛先となる Cloud Storage バケットの名前に置き換えます。location_expression フィールドは、Common Expression Language（CEL）式です。
DUMPER_BUCKET に、次の内容を含む別の構成 YAML ファイル（接尾辞 config.yaml）を作成します。
```
    type: experimental_object_rewriter
    relation:
      - match:
          schema: SOURCE_DATABASE
        outputName:
          database: null
          schema: TARGET_DATABASE
```
- SOURCE_DATABASE と TARGET_DATABASE は、選択したメタストアに応じて、ソースデータベース名と Dataproc Metastore データベースまたは BigQuery データセットの名前に置き換えます。BigLake Metastore 用にデータベースを構成する場合は、BigQuery データセットが存在することを確認します。
これらの構成 YAML の詳細については、YAML 構成ファイルを作成するためのガイドラインをご覧ください。

次のコマンドを使用して、テーブルマッピング YAML ファイルを生成します。

curl -d '{
  "tasks": {
      "string": {
        "type": "HiveQL2BigQuery_Translation",
        "translation_details": {
            "target_base_uri": "TRANSLATION_OUTPUT_BUCKET",
            "source_target_mapping": {
              "source_spec": {
                  "base_uri": "DUMPER_BUCKET"
              }
            },
            "target_types": ["metadata"]
        }
      }
  }
  }' \
  -H "Content-Type:application/json" \
  -H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2alpha/projects/PROJECT_ID/locations/LOCATION/workflows

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

TRANSLATION_OUTPUT_BUCKET:（省略可）変換出力用の Cloud Storage バケットを指定します。詳細については、翻訳出力の使用をご覧ください。
DUMPER_BUCKET: hive-dumper-output.zip と構成 YAML ファイルを格納している Cloud Storage バケットのベース URI。
TOKEN: OAuth トークン。これは、コマンドラインでコマンド gcloud auth print-access-token を使用して生成できます。
PROJECT_ID: 変換を処理するプロジェクト。
LOCATION: ジョブが処理されるロケーション。たとえば、eu や us です。

このジョブのステータスをモニタリングします。完了すると、データベース内の各テーブルのマッピングファイルが TRANSLATION_OUTPUT_BUCKET の事前定義されたパスに生成されます。

HDFS データレイク転送をモニタリングする

HDFS データレイク転送のスケジュールを設定したら、bq コマンドラインツールのコマンドを使用して転送ジョブをモニタリングできます。転送ジョブのモニタリングについては、転送を表示するをご覧ください。

テーブルの移行ステータスをトラッキングする

dwh-dts-status ツールを実行して、転送構成または特定のデータベース内のすべての転送済みテーブルのステータスをモニタリングすることもできます。dwh-dts-status ツールを使用して、プロジェクト内のすべての転送構成を一覧表示することもできます。

始める前に

dwh-dts-status ツールを使用するには、まず次の操作を行います。

dwh-migration-tools GitHub リポジトリから dwh-migration-tool パッケージをダウンロードして、dwh-dts-status ツールを入手します。
次のコマンドを使用して、アカウントを Google Cloud に対して認証します。
```
gcloud auth application-default login
```
詳細については、アプリケーションのデフォルト認証情報の仕組みをご覧ください。
ユーザーに bigquery.admin ロールと logging.viewer ロールがあることを確認します。IAM ロールの詳細については、アクセス制御のリファレンスをご覧ください。

プロジェクト内のすべての転送構成を一覧表示する

プロジェクト内のすべての転送構成を一覧表示するには、次のコマンドを使用します。

  ./dwh-dts-status --list-transfer-configs --project-id=[PROJECT_ID] --location=[LOCATION]

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

PROJECT_ID: 転送を実行している Google Cloud プロジェクト ID。
LOCATION: 転送構成が作成されたロケーション。

このコマンドは、転送構成の名前と ID のリストを含むテーブルを出力します。

構成内のすべてのテーブルのステータスを表示する

転送構成に含まれるすべてのテーブルのステータスを表示するには、次のコマンドを使用します。

  ./dwh-dts-status --list-status-for-config --project-id=[PROJECT_ID] --config-id=[CONFIG_ID] --location=[LOCATION]

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

PROJECT_ID: 転送を実行している Google Cloud プロジェクト ID。
LOCATION: 転送構成が作成されたロケーション。
CONFIG_ID: 指定された転送構成の ID。

このコマンドは、指定された転送構成内のテーブルのリストと転送ステータスを含むテーブルを出力します。転送ステータスは、PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED のいずれかの値になります。

データベース内のすべてのテーブルのステータスを表示する

特定のデータベースから転送されたすべてのテーブルのステータスを表示するには、次のコマンドを使用します。

  ./dwh-dts-status --list-status-for-database --project-id=[PROJECT_ID] --database=[DATABASE]

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

PROJECT_ID: 転送を実行している Google Cloud プロジェクト ID。
DATABASE: 指定したデータベースの名前。

このコマンドは、指定されたデータベース内のテーブルのリストとその転送ステータスを含むテーブルを出力します。転送ステータスは、PENDING、RUNNING、SUCCEEDED、FAILED、CANCELLED のいずれかの値になります。

HDFS データレイクからテーブルを移行する

制限事項

始める前に

移行するファイル用の Cloud Storage バケットを作成する

Apache Hive のメタデータ ファイルを生成する

API を有効にする

権限を構成する

Storage Transfer エージェントを構成する

HDFS データレイク転送のスケジュールを設定する

データの取り込みオプション

増分転送

転送のスケジュール設定オプション

変換出力を構成する

HDFS データレイク転送をモニタリングする

テーブルの移行ステータスをトラッキングする

始める前に

プロジェクト内のすべての転送構成を一覧表示する

構成内のすべてのテーブルのステータスを表示する

データベース内のすべてのテーブルのステータスを表示する

Apache Hive のメタデータファイルを生成する