Cloud Storage Text to Firestore テンプレート

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 のようにします。
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 の例をご覧ください。
firestoreWriteProjectId Firestore エンティティを書き込む Google Cloud プロジェクト ID
firestoreHintNumWorkers （省略可）Firestore のランプアップ スロットリング ステップで予想されるワーカー数のヒント。デフォルトは、500 です。
errorWritePath 処理中に発生したエラーを書き込むために使用するエラーログ出力ファイル。例: gs://bucket-name/errors.txt

ユーザー定義関数

必要であれば、ユーザー定義関数（UDF）を記述して、このテンプレートを拡張できます。このテンプレートは入力要素ごとに UDF を呼び出します。要素のペイロードは、JSON 文字列としてシリアル化されます。詳細については、Dataflow テンプレートのユーザー定義関数を作成するをご覧ください。

関数の仕様

UDF の仕様は次のとおりです。

  • 入力: Cloud Storage 入力ファイルのテキスト行。
  • 出力: JSON 文字列としてシリアル化された Entity。

テンプレートを実行する

コンソール

  1. Dataflow の [テンプレートからジョブを作成] ページに移動します。
    2. [テンプレートからジョブを作成] に移動
  2. [ジョブ名] フィールドに、固有のジョブ名を入力します。
  3. （省略可）[リージョン エンドポイント] で、プルダウン メニューから値を選択します。デフォルトのリージョンは us-central1 です。

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

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

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 プロジェクトの 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）
  • 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 上のエラーファイルの目的のパス

次のステップ