Cloud Storage Text to Spanner テンプレートは、Storage から CSV テキスト ファイルを読み取り、Spanner データベースにインポートするバッチ パイプラインです。
パイプラインの要件
- ターゲットの Spanner データベースとテーブルが存在している必要があります。
- Cloud Storage バケットの読み取り権限と、対象の Spanner データベースに対する書き込み権限が必要です。
- CSV ファイルを含む入力 Cloud Storage パスが存在している必要があります。
- CSV ファイルの JSON 記述を含むインポート マニフェスト ファイルを作成し、そのマニフェストを Cloud Storage に保存する必要があります。
- ターゲットの Spanner データベースにすでにスキーマがある場合、マニフェスト ファイルで指定された列は、ターゲット データベースのスキーマ内の対応する列と同じデータ型である必要があります。
-
ASCII または UTF-8 でエンコードされたマニフェスト ファイルは、次の形式に一致する必要があります。
- インポートするテキスト ファイルは、ASCII または UTF-8 エンコードの CSV 形式である必要があります。UTF-8 エンコード ファイルではバイト オーダー マーク(BOM)を使用しないことをおすすめします。
- データは次のタイプのいずれかに一致する必要があります。
GoogleSQL
BOOL INT64 FLOAT64 NUMERIC STRING DATE TIMESTAMP BYTES JSON
PostgreSQL
boolean bigint double precision numeric character varying, text date timestamp with time zone bytea
テンプレートのパラメータ
必須パラメータ
- instanceId: Spanner データベースのインスタンス ID。
- databaseId: Spanner データベースのデータベース ID。
- importManifest: マニフェスト ファイルのインポート時に使用する Cloud Storage のパス。例:
gs://your-bucket/your-folder/your-manifest.json
オプション パラメータ
- spannerHost: テンプレート内で呼び出す Cloud Spanner のエンドポイント。テストでのみ使われます例:
https://batch-spanner.googleapis.com
デフォルトは https://batch-spanner.googleapis.com です。 - columnDelimiter: ソースファイルが使用する列区切り文字。デフォルト値は
,
です。例:,
- fieldQualifier: columnDelimiter を含むソースファイルで値を囲む必要がある文字。デフォルト値は二重引用符です。
- trailingDelimiter: ソースファイルの行の末尾に区切り文字があるかどうかを指定します(つまり、
columnDelimiter
文字が各行の最後の列の値の後に表示されるかどうか)。デフォルト値はtrue
です。 - escape: ソースファイルが使用するエスケープ文字。デフォルトでは、このパラメータは設定されておらず、テンプレートでエスケープ文字は使用されません。
- nullString:
NULL
値を表す文字列。デフォルトでは、このパラメータは設定されておらず、テンプレートで null 文字列は使用されません。 - dateFormat: 日付列を解析するために使用される形式。デフォルトでは、パイプラインは日付列を
yyyy-M-d[' 00:00:00']
として解析します。たとえば2019-01-31
または2019-1-1 00:00:00
とします。日付形式が異なる場合は、java.time.format.DateTimeFormatter(https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html)のパターンを使用して形式を指定します。 - timestampFormat: timestamp 列を解析するために使用される形式。タイムスタンプが Long 整数の場合は、Unix エポック時間として解析されます。それ以外の場合は、java.time.format.DateTimeFormatter.ISO_INSTANT(https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT)形式を使用して、文字列として解析されます。その他の場合では、独自のパターン文字列を指定します。たとえば、
Jan 21 1998 01:02:03.456+08:00
という形式のタイムスタンプには、「MMM dd yyyy HH:mm:ss.SSSVV
」を使用します。 - spannerProjectId: Spanner データベースを含む Google Cloud プロジェクトの ID。設定されていない場合は、デフォルトの Google Cloud プロジェクトのプロジェクト ID が使用されます。
- spannerPriority: Spanner 呼び出しのリクエストの優先度。有効な値は
HIGH
、MEDIUM
、LOW
です。デフォルト値はMEDIUM
です。 - handleNewLine:
true
の場合、入力データに改行文字を含めることができます。それ以外の場合は、改行文字が原因でエラーが発生します。デフォルト値はfalse
です。改行処理を有効にすると、パフォーマンスが低下する可能性があります。 - invalidOutputPath: インポートできない行を書き込むときに使用する Cloud Storage パス。例:
gs://your-bucket/your-path
デフォルトは空です。
日付形式やタイムスタンプ形式をカスタマイズする必要がある場合は、有効な java.time.format.DateTimeFormatter
パターンであることを確認してください。date 列と timestamp 列のカスタマイズされた形式のその他の例を次の表に示します。
タイプ | 入力値 | フォーマット | 備考 |
---|---|---|---|
DATE |
2011-3-31 | デフォルトでは、テンプレートはこの形式を解析できます。dateFormat パラメータを指定する必要はありません。 |
|
DATE |
2011-3-31 00:00:00 | デフォルトでは、テンプレートはこの形式を解析できます。形式を指定する必要はありません。必要に応じて yyyy-M-d' 00:00:00' が使用できます。 |
|
DATE |
2018 年 4 月 1 日 | dd MMM, yy | |
DATE |
西暦 2019 年 4 月 3 日水曜日 | EEEE, LLLL d, yyyy G | |
TIMESTAMP |
2019-01-02T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z |
デフォルトの形式 ISO_INSTANT はこのタイプのタイムスタンプを解析できます。timestampFormat パラメータを指定する必要はありません。 |
|
TIMESTAMP |
1568402363 | デフォルトでは、テンプレートはこのタイプのタイムスタンプを解析し、Unix エポック時間として扱います。 | |
TIMESTAMP |
2008 年 6 月 3 日(火曜日)11:05:30 GMT | EEE, d MMM yyyy HH:mm:ss VV | |
TIMESTAMP |
2018 年 12 月 31 日 110530.123 太平洋標準時 | yyyy/MM/dd HHmmss.SSSz | |
TIMESTAMP |
2019-01-02T11:22:33Z または 2019-01-02T11:22:33.123Z | yyyy-MM-dd'T'HH:mm:ss [.SSS]VV | 入力列が 2019-01-02T11:22:33Z と 2019-01-02T11:22:33.123Z の場合、この形式のタイムスタンプはデフォルトの形式で解析できます。独自のフォーマット パラメータを指定する必要はありません。yyyy-MM-dd'T'HH:mm:ss[.SSS]VV を使用すると、両方のケースに対応できます。接尾辞「Z」は文字リテラルではなくタイムゾーン ID として解析する必要があるため、yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z' は使用できません。内部的には、タイムスタンプ列は java.time.Instant に変換されます。そのため、UTC で指定するか、タイムゾーン情報を設定する必要があります。2019-01-02 11:22:33 のようなローカル日時は、有効な java.time.Instant として解析されません。 |
テンプレートを実行する
コンソール
- Dataflow の [テンプレートからジョブを作成] ページに移動します。 [テンプレートからジョブを作成] に移動
- [ジョブ名] フィールドに、固有のジョブ名を入力します。
- (省略可)[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは
us-central1
です。Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。
- [Dataflow テンプレート] プルダウン メニューから、[ the Text Files on Cloud Storage to Cloud Spanner template] を選択します。
- 表示されたパラメータ フィールドに、パラメータ値を入力します。
- [ジョブを実行] をクリックします。
gcloud
シェルまたはターミナルで、テンプレートを実行します。
gcloud dataflow jobs run JOB_NAME \ --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \ --region REGION_NAME \ --parameters \ instanceId=INSTANCE_ID,\ databaseId=DATABASE_ID,\ importManifest=GCS_PATH_TO_IMPORT_MANIFEST
次のように置き換えます。
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 インスタンス IDDATABASE_ID
: Spanner データベース IDGCS_PATH_TO_IMPORT_MANIFEST
: インポート マニフェスト ファイルへの Cloud Storage パス
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_Text_to_Cloud_Spanner { "jobName": "JOB_NAME", "parameters": { "instanceId": "INSTANCE_ID", "databaseId": "DATABASE_ID", "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST" }, "environment": { "machineType": "n1-standard-2" } }
次のように置き換えます。
PROJECT_ID
: Dataflow ジョブを実行する Google Cloud プロジェクトの IDJOB_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 インスタンス IDDATABASE_ID
: Spanner データベース IDGCS_PATH_TO_IMPORT_MANIFEST
: インポート マニフェスト ファイルへの Cloud Storage パス
次のステップ
- Dataflow テンプレートについて学習する。
- Google 提供のテンプレートのリストを確認する。