Cloud Storage Text to Firestore テンプレートは、Cloud Storage に保存されている JSON ドキュメントから Firestore にインポートするバッチ パイプラインです。
パイプラインの要件
Firestore が宛先プロジェクトで有効にされている必要があります。
入力形式
各入力ファイルには改行区切りの JSON が含まれている必要があります。各行には Datastore の Entity
データ型の JSON 表現が含まれます。
たとえば、次の JSON は Users
という名前のコレクション内のドキュメントを表します。この例では、読みやすいように書式設定されていますが、各ドキュメントは 1 行の入力として表す必要があります。
{ "key": { "partitionId": { "projectId": "my-project" }, "path": [ { "kind": "users", "name": "alovelace" } ] }, "properties": { "first": { "stringValue": "Ada" }, "last": { "stringValue": "Lovelace" }, "born": { "integerValue": "1815", "excludeFromIndexes": true } } }
ドキュメント モデルの詳細については、エンティティ、プロパティ、キーをご覧ください。
テンプレートのパラメータ
必須パラメータ
- textReadPattern: テキスト データファイルの場所を指定する Cloud Storage のパスパターン。例:
gs://mybucket/somepath/*.json
- firestoreWriteProjectId: Firestore エンティティの書き込み先となる Google Cloud プロジェクトの ID。
- errorWritePath: 処理中に発生したエラーを書き込むために使用するエラーログ出力ファイル(例: gs://your-bucket/errors/)。
オプション パラメータ
- javascriptTextTransformGcsPath: 使用する JavaScript ユーザー定義関数(UDF)を定義する .js ファイルの Cloud Storage URI。たとえば、
gs://my-bucket/my-udfs/my_file.js
のようにします。 - javascriptTextTransformFunctionName: 使用する JavaScript ユーザー定義関数(UDF)の名前。たとえば、JavaScript 関数コードが
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例(https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples)をご覧ください。 - firestoreHintNumWorkers: Firestore のランプアップ スロットリング ステップで予想されるワーカー数のヒント。デフォルトは 500 です。
ユーザー定義関数
必要であれば、ユーザー定義関数(UDF)を記述して、このテンプレートを拡張できます。このテンプレートは入力要素ごとに UDF を呼び出します。要素のペイロードは、JSON 文字列としてシリアル化されます。詳細については、Dataflow テンプレートのユーザー定義関数を作成するをご覧ください。
関数の仕様
UDF の仕様は次のとおりです。
- 入力: Cloud Storage 入力ファイルのテキスト行。
- 出力: JSON 文字列としてシリアル化された
Entity
。
テンプレートを実行する
コンソール
- Dataflow の [テンプレートからジョブを作成] ページに移動します。 [テンプレートからジョブを作成] に移動
- [ジョブ名] フィールドに、固有のジョブ名を入力します。
- (省略可)[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは
us-central1
です。Dataflow ジョブを実行できるリージョンのリストについては、Dataflow のロケーションをご覧ください。
- [Dataflow テンプレート] プルダウン メニューから、[ the Text Files on Cloud Storage to Firestore template] を選択します。
- 表示されたパラメータ フィールドに、パラメータ値を入力します。
- [ジョブを実行] をクリックします。
gcloud
シェルまたはターミナルで、テンプレートを実行します。
gcloud dataflow jobs run JOB_NAME \ --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Firestore \ --region REGION_NAME \ --parameters \ textReadPattern=PATH_TO_INPUT_TEXT_FILES,\ javascriptTextTransformGcsPath=PATH_TO_JAVASCRIPT_UDF_FILE,\ javascriptTextTransformFunctionName=JAVASCRIPT_FUNCTION,\ firestoreWriteProjectId=PROJECT_ID,\ errorWritePath=ERROR_FILE_WRITE_PATH
次のように置き換えます。
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
)PATH_TO_INPUT_TEXT_FILES
: Cloud Storage 上の入力ファイル パターンJAVASCRIPT_FUNCTION
: 使用する JavaScript ユーザー定義関数(UDF)の名前たとえば、JavaScript 関数が
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例をご覧ください。PATH_TO_JAVASCRIPT_UDF_FILE
: 使用する JavaScript ユーザー定義関数(UDF)を定義する.js
ファイルの Cloud Storage URI(例:gs://my-bucket/my-udfs/my_file.js
)ERROR_FILE_WRITE_PATH
: 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_Firestore { "jobName": "JOB_NAME", "parameters": { "textReadPattern": "PATH_TO_INPUT_TEXT_FILES", "javascriptTextTransformGcsPath": "PATH_TO_JAVASCRIPT_UDF_FILE", "javascriptTextTransformFunctionName": "JAVASCRIPT_FUNCTION", "firestoreWriteProjectId": "PROJECT_ID", "errorWritePath": "ERROR_FILE_WRITE_PATH" }, "environment": { "zone": "us-central1-f" } }
次のように置き換えます。
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
)PATH_TO_INPUT_TEXT_FILES
: Cloud Storage 上の入力ファイル パターンJAVASCRIPT_FUNCTION
: 使用する JavaScript ユーザー定義関数(UDF)の名前たとえば、JavaScript 関数が
myTransform(inJson) { /*...do stuff...*/ }
の場合、関数名はmyTransform
です。JavaScript UDF の例については、UDF の例をご覧ください。PATH_TO_JAVASCRIPT_UDF_FILE
: 使用する JavaScript ユーザー定義関数(UDF)を定義する.js
ファイルの Cloud Storage URI(例:gs://my-bucket/my-udfs/my_file.js
)ERROR_FILE_WRITE_PATH
: Cloud Storage 上のエラーファイルの目的のパス
次のステップ
- Dataflow テンプレートについて学習する。
- Google 提供のテンプレートのリストを確認する。