Cloud Storage 文字到 Firestore 範本

「Cloud Storage 文字到 Firestore」範本是一種批次管道,可將儲存在 Cloud Storage 的 JSON 文件匯入 Firestore。

管道相關規定

目的地專案必須啟用 Firestore。

輸入格式

每個輸入檔案都必須包含以換行符號分隔的 JSON,其中每行都包含 Datastore Entity 資料類型的 JSON 表示法。

舉例來說,下列 JSON 代表名為 Users 的集合中的文件。範例已設定格式,方便閱讀,但每份文件都必須以單行輸入內容的形式呈現。

{
  "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 user-defined function (UDF) 的 .js 檔案 Cloud Storage URI。例如:gs://my-bucket/my-udfs/my_file.js。
  • javascriptTextTransformFunctionName:要使用的 JavaScript user-defined function (UDF) 名稱。例如,如果您的 JavaScript 函式程式碼是 myTransform(inJson) { /*...do stuff...*/ },則函式名稱就是 myTransform。如需 JavaScript UDF 範例,請參閱 UDF 範例 (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples)。
  • firestoreHintNumWorkers:Firestore 升速節流步驟中預期 worker 數量的提示。預設值為 500。

User-defined function

您可以視需要撰寫 user-defined function (UDF) 來擴充這個範本。範本會針對每個輸入元素呼叫 UDF。元素酬載會序列化為 JSON 字串。詳情請參閱「為 Dataflow 範本建立 user-defined function」。

函式規格

UDF 的規格如下:

  • 輸入:Cloud Storage 輸入檔案中的一行文字。
  • 輸出:以 JSON 字串序列化的 Entity。

執行範本

控制台

  1. 前往 Dataflow 的「Create job from template」(依據範本建立工作) 頁面。
  2. 前往「依範本建立工作」
  3. 在「Job name」(工作名稱) 欄位中,輸入專屬工作名稱。
  4. 選用:如要使用區域端點,請從下拉式選單中選取值。預設區域為 us-central1。

    如需可執行 Dataflow 工作的區域清單,請參閱「Dataflow 位置」。

  5. 從「Dataflow 範本」下拉式選單中,選取「Cloud Storage 中的文字檔案至 Firestore」範本。
  6. 在提供的參數欄位中輸入參數值。
  7. 按一下「Run Job」(執行工作)。

gcloud

在殼層或終端機中執行範本:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates/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,使用範本的最新版本,該版本位於 bucket 中非依日期命名的上層資料夾:gs://dataflow-templates/latest/
    • 版本名稱,例如 2023-09-12-00_RC00,可使用特定版本的範本,該範本會以巢狀結構存放在 bucket 中相應的依日期命名的上層資料夾中:gs://dataflow-templates/
  • REGION_NAME:您要部署 Dataflow 工作的區域,例如 us-central1
  • PATH_TO_INPUT_TEXT_FILES:Cloud Storage 上的輸入檔案模式
  • JAVASCRIPT_FUNCTION: 您要使用的 JavaScript user-defined function (UDF) 名稱

    例如,如果您的 JavaScript 函式程式碼是 myTransform(inJson) { /*...do stuff...*/ },則函式名稱就是 myTransform。如需 JavaScript UDF 範例,請參閱「UDF 範例」。

  • PATH_TO_JAVASCRIPT_UDF_FILE: 定義要使用的 JavaScript user-defined function (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/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,使用範本的最新版本,該版本位於 bucket 中非依日期命名的上層資料夾:gs://dataflow-templates/latest/
    • 版本名稱,例如 2023-09-12-00_RC00,可使用特定版本的範本,該範本會以巢狀結構存放在 bucket 中相應的依日期命名的上層資料夾中:gs://dataflow-templates/
  • LOCATION:您要部署 Dataflow 工作的區域,例如 us-central1
  • PATH_TO_INPUT_TEXT_FILES:Cloud Storage 上的輸入檔案模式
  • JAVASCRIPT_FUNCTION: 您要使用的 JavaScript user-defined function (UDF) 名稱

    例如,如果您的 JavaScript 函式程式碼是 myTransform(inJson) { /*...do stuff...*/ },則函式名稱就是 myTransform。如需 JavaScript UDF 範例,請參閱「UDF 範例」。

  • PATH_TO_JAVASCRIPT_UDF_FILE: 定義要使用的 JavaScript user-defined function (UDF) 的 .js 檔案 Cloud Storage URI,例如 gs://my-bucket/my-udfs/my_file.js
  • ERROR_FILE_WRITE_PATH:Cloud Storage 錯誤檔案的路徑

後續步驟