Cloud Storage Avro to Spanner テンプレート

Cloud Storage Avro files to Cloud Spanner テンプレートは、Cloud Storage に保存されている Spanner からエクスポートされた Avro ファイルを読み取り、それらのファイルを Spanner データベースにインポートするバッチ パイプラインです。

パイプラインの要件

  • ターゲットの Spanner データベースが存在し、空であることが必要です。
  • Cloud Storage バケットの読み取り権限と、対象の Spanner データベースに対する書き込み権限が必要です。
  • 入力された Cloud Storage パスが存在する必要があります。また、インポートするファイルの JSON 記述を含む spanner-export.json ファイルがそこに格納されている必要があります。
  • ソースの Avro ファイルに主キーがない場合は、テンプレートを実行する前に、主キーのある空の Spanner テーブルを作成する必要があります。Avro ファイルで主キーを定義している場合、この手順は必要ありません。

テンプレートのパラメータ

必須パラメータ

  • instanceId : Spanner データベースのインスタンス ID。
  • databaseId: Spanner データベースのデータベース ID。
  • inputDir: Avro ファイルのインポート元となる Cloud Storage のパス。

オプション パラメータ

  • spannerHost: テンプレートで呼び出す Cloud Spanner エンドポイント。テスト専用です(例: https://batch-spanner.googleapis.com)。デフォルトは https://batch-spanner.googleapis.com です。
  • waitForIndexes: true の場合、パイプラインはインデックスが作成されるまで待機します。false の場合、インデックスがバックグラウンドで作成されている間に、ジョブが完了する可能性があります。デフォルト値は false です。
  • waitForForeignKeys: true の場合、パイプラインは外部キーが作成されるまで待機します。false の場合、外部キーがバックグラウンドで作成されている間に、ジョブが完了する可能性があります。デフォルト値は false です。
  • waitForChangeStreams: true の場合、パイプラインは変更ストリームが作成されるまで待機します。false の場合、変更ストリームがバックグラウンドで作成されている間に、ジョブが完了する可能性があります。デフォルト値は true です。
  • waitForSequences: デフォルトでは、シーケンスの作成時にインポート パイプラインはブロックされます。false の場合、バックグラウンドでシーケンスを作成していても、インポート パイプラインが完了することがあります。
  • earlyIndexCreateFlag: インデックスの早期作成を有効にするかどうかを指定します。テンプレートで多くの DDL ステートメントを実行している場合は、データを読み込む前にインデックスを作成するほうが効率的です。デフォルトの動作では、DDL ステートメントの数がしきい値を超えたときに、インデックスが先に作成されます。この機能を無効にするには、earlyIndexCreateFlagfalse に設定します。デフォルト値は true です。
  • spannerProjectId: Spanner データベースを含む Google Cloud プロジェクトの ID。設定されていない場合は、デフォルトの Google Cloud プロジェクトが使用されます。
  • ddlCreationTimeoutInMinutes: テンプレートによって実行される DDL ステートメントのタイムアウト(分単位)。デフォルト値は 30 分です。
  • spannerPriority: Spanner 呼び出しのリクエストの優先度。有効な値は HIGHMEDIUMLOW です。デフォルト値は MEDIUM です。

テンプレートを実行する

コンソール

  1. Dataflow の [テンプレートからジョブを作成] ページに移動します。
  2. [テンプレートからジョブを作成] に移動
  3. [ジョブ名] フィールドに、固有のジョブ名を入力します。

    Google Cloud コンソールの Spanner インスタンス ページにジョブを表示するには、ジョブ名が次の形式になっている必要があります。

    cloud-spanner-import-SPANNER_INSTANCE_ID-SPANNER_DATABASE_NAME

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

    • SPANNER_INSTANCE_ID: Spanner インスタンスの ID
    • SPANNER_DATABASE_NAME: Spanner データベースの名前
  4. (省略可)[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは us-central1 です。

    Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。

  5. [Dataflow テンプレート] プルダウン メニューから、[ the Avro Files on Cloud Storage to Cloud Spanner template] を選択します。
  6. 表示されたパラメータ フィールドに、パラメータ値を入力します。
  7. [ジョブを実行] をクリックします。

gcloud

シェルまたはターミナルで、テンプレートを実行します。

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Avro_to_Cloud_Spanner \
    --region REGION_NAME \
    --staging-location GCS_STAGING_LOCATION \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
inputDir=GCS_DIRECTORY

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

  • JOB_NAME: 一意の任意のジョブ名
  • VERSION: 使用するテンプレートのバージョン

    使用できる値は次のとおりです。

    • latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ(gs://dataflow-templates-REGION_NAME/latest/)にあります。
    • バージョン名(例: 2023-09-12-00_RC00)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
  • REGION_NAME: Dataflow ジョブをデプロイするリージョン(例: us-central1
  • INSTANCE_ID: データベースを含む Spanner インスタンスの ID
  • DATABASE_ID: インポート先の Spanner データベースの ID
  • GCS_DIRECTORY: Avro ファイルのインポート元となる Cloud Storage パス。例: gs://mybucket/somefolder

API

REST API を使用してテンプレートを実行するには、HTTP POST リクエストを送信します。API とその認証スコープの詳細については、projects.templates.launch をご覧ください。

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Avro_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "inputDir": "gs://GCS_DIRECTORY"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

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

  • PROJECT_ID: Dataflow ジョブを実行する Google Cloud プロジェクトの ID
  • JOB_NAME: 一意の任意のジョブ名
  • VERSION: 使用するテンプレートのバージョン

    使用できる値は次のとおりです。

    • latest: 最新バージョンのテンプレートを使用します。このテンプレートは、バケット内で日付のない親フォルダ(gs://dataflow-templates-REGION_NAME/latest/)にあります。
    • バージョン名(例: 2023-09-12-00_RC00)。特定のバージョンのテンプレートを使用します。このテンプレートは、バケット内で対応する日付の親フォルダ(gs://dataflow-templates-REGION_NAME/)にあります。
  • LOCATION: Dataflow ジョブをデプロイするリージョン(例: us-central1
  • INSTANCE_ID: データベースを含む Spanner インスタンスの ID
  • DATABASE_ID: インポート先の Spanner データベースの ID
  • GCS_DIRECTORY: Avro ファイルのインポート元となる Cloud Storage パス。例: gs://mybucket/somefolder

次のステップ