Datastream 到 BigQuery (串流) 範本

「Datastream 到 BigQuery」範本是串流管道,可讀取 Datastream 資料並複製到 BigQuery。範本會使用 Pub/Sub 通知從 Cloud Storage 讀取資料,並將資料複製到依時間分區的 BigQuery 暫存資料表。複製完成後,範本會在 BigQuery 中執行 MERGE,將所有變更資料擷取 (CDC) 變更 upsert 至來源資料表的副本。請指定 gcsPubSubSubscription 參數,從 Pub/Sub 通知讀取資料,或提供 inputFilePattern 參數,直接從 Cloud Storage 中的檔案讀取資料。

範本會處理建立及更新由複製作業管理的 BigQuery 資料表。需要資料定義語言 (DDL) 時,系統會回呼 Datastream,擷取來源資料表結構定義,並將其轉譯為 BigQuery 資料類型。支援的操作包括:

  • 插入資料時,系統會建立新資料表。
  • 新資料欄會新增至 BigQuery 資料表,初始值為空值。
  • BigQuery 會忽略捨棄的資料欄,未來的值會是空值。
  • 重新命名的資料欄會以新資料欄的形式新增至 BigQuery。
  • 類型變更不會傳播至 BigQuery。

建議您使用至少一次串流模式執行這個管道,因為範本會將臨時 BigQuery 資料表的資料合併至主要 BigQuery 資料表,並執行刪除重複資料作業。管道中的這個步驟表示,使用精確一次串流模式不會帶來額外好處。

管道相關規定

  • 準備複製或已在複製資料的 Datastream 串流。
  • Datastream 資料已啟用 Cloud Storage Pub/Sub 通知。
  • BigQuery 目的地資料集已建立,且 Compute Engine 服務帳戶已取得這些資料集的管理員存取權。
  • 來源資料表必須有主鍵,才能建立目的地副本資料表。
  • MySQL 或 Oracle 來源資料庫。不支援 PostgreSQL 和 SQL Server 資料庫。

範本參數

必要參數

  • inputFileFormat:Datastream 產生的輸出檔案格式。允許的值為 avro 和 json。預設為 avro。
  • outputStagingDatasetTemplate:包含暫存資料表的資料集名稱。這項參數支援範本,例如 {_metadata_dataset}_log 或 my_dataset_log。這個參數通常是資料集名稱。預設值為 {_metadata_dataset}。注意:如果是 MySQL 來源,資料庫名稱會對應至 {_metadata_schema},而非 {_metadata_dataset}。
  • outputDatasetTemplate:包含副本資料表的資料集名稱。這項參數支援範本,例如 {_metadata_dataset} 或 my_dataset。這個參數通常是資料集名稱。預設值為 {_metadata_dataset}。注意:如果是 MySQL 來源,資料庫名稱會對應至 {_metadata_schema},而非 {_metadata_dataset}。
  • deadLetterQueueDirectory:Dataflow 用於寫入無效信件佇列輸出的路徑。這個路徑不得與 Datastream 檔案輸出路徑相同。預設值為 empty。

選用參數

  • inputFilePattern:Datastream 檔案在 Cloud Storage 的輸出位置,格式為 gs://<BUCKET_NAME>/<ROOT_PATH>/。
  • gcsPubSubSubscription:Cloud Storage 用來通知 Dataflow 有新檔案可供處理的 Pub/Sub 訂閱項目,格式為 projects/<PROJECT_ID>/subscriptions/<SUBSCRIPTION_NAME>。
  • streamName:要輪詢結構定義資訊的串流名稱或範本。預設值為:{_metadata_stream}。通常使用預設值即可。
  • rfcStartDateTime:從 Cloud Storage 擷取資料時使用的起始日期時間 (https://tools.ietf.org/html/rfc3339)。預設值:1970-01-01T00:00:00.00Z。
  • fileReadConcurrency:要讀取的並行 DataStream 檔案數量。預設為 10。
  • outputProjectId:Google Cloud 專案 ID,其中包含要輸出資料的 BigQuery 資料集。這項參數的預設值為 Dataflow 管道執行的專案。
  • outputStagingTableNameTemplate:用於命名暫存資料表的範本。例如,{_metadata_table}。預設值為 {_metadata_table}_log。
  • outputTableNameTemplate:副本資料表名稱使用的範本,例如 {_metadata_table}。預設值為 {_metadata_table}。
  • ignoreFields:在 BigQuery 中要忽略的欄位,以半形逗號分隔。預設值:_metadata_stream,_metadata_schema,_metadata_table,_metadata_source,_metadata_tx_id,_metadata_dlq_reconsumed,_metadata_primary_keys,_metadata_error,_metadata_retry_count。例如:_metadata_stream,_metadata_schema。
  • mergeFrequencyMinutes:指定資料表兩次合併作業之間的間隔分鐘數。預設值為 5。
  • dlqRetryMinutes:DLQ 重試間隔時間 (以分鐘為單位)。預設值為 10。
  • dataStreamRootUrl:Datastream API 根網址。預設值為:https://datastream.googleapis.com/。
  • applyMerge:是否要停用工作的 MERGE 查詢。預設值為 true。
  • mergeConcurrency:並行 BigQuery MERGE 查詢數量。只有在 applyMerge 設為 true 時才會生效。預設值為 30。
  • partitionRetentionDays:執行 BigQuery 合併作業時,分區保留的天數。預設值為 1。
  • useStorageWriteApiAtLeastOnce:只有在啟用 Use BigQuery Storage Write API 時,這項參數才會生效。如果為 true,Storage Write API 會使用至少一次語意。否則,系統會使用僅一次語意。預設為 false。
  • datastreamSourceType:覆寫 Datastream CDC 資料的來源類型偵測。指定後,系統會使用這個值,而非從 read_method 欄位衍生來源類型。有效值包括「mysql」、「postgresql」、「oracle」、「sqlserver」等。如果 read_method 欄位包含「cdc」,且無法自動判斷實際來源類型,這個參數就很有用。
  • 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)。
  • javascriptTextTransformReloadIntervalMinutes:指定重新載入 UDF 的頻率 (以分鐘為單位)。如果值大於 0,Dataflow 會定期檢查 Cloud Storage 中的 UDF 檔案,並在檔案修改後重新載入 UDF。這個參數可讓您在管道執行期間更新 UDF,不必重新啟動工作。如果值為 0,則會停用 UDF 重新載入功能。預設值為 0。
  • pythonTextTransformGcsPath:Python 程式碼的 Cloud Storage 路徑模式,其中包含 user-defined function。例如:gs://your-bucket/your-transforms/*.py。
  • pythonRuntimeVersion:這個 Python UDF 要使用的執行階段版本。
  • pythonTextTransformFunctionName:要從 JavaScript 檔案呼叫的函式名稱。只能使用英文字母、數字和底線。例如:transform_udf1。
  • runtimeRetries:執行階段在失敗前重試的次數。預設為:5。
  • useStorageWriteApi:如果為 true,管道會使用 BigQuery Storage Write API (https://cloud.google.com/bigquery/docs/write-api)。預設值為 false。詳情請參閱「使用 Storage Write API」(https://beam.apache.org/documentation/io/built-in/google-bigquery/#storage-write-api)。
  • numStorageWriteApiStreams:使用 Storage Write API 時,指定寫入串流的數量。如果 useStorageWriteApi 為 true 且 useStorageWriteApiAtLeastOnce 為 false,則必須設定這個參數。預設為:0。
  • storageWriteApiTriggeringFrequencySec:使用 Storage Write API 時,指定觸發頻率 (以秒為單位)。如果 useStorageWriteApi 為 true 且 useStorageWriteApiAtLeastOnce 為 false,則必須設定這個參數。

User-defined function

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

函式規格

UDF 的規格如下:

  • 輸入:CDC 資料,序列化為 JSON 字串。
  • 輸出:符合 BigQuery 目的地資料表結構定義的 JSON 字串。
  • 執行範本

    控制台

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

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

    5. 從「Dataflow template」(Dataflow 範本) 下拉式選單中,選取「Datastream to BigQuery」範本。
    6. 在提供的參數欄位中輸入參數值。
    7. 選用:如要從「僅需處理一次」切換至「至少一次串流模式」,請選取「At Least Once」(至少一次)。
    8. 按一下「Run Job」(執行工作)。

    gcloud

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

    gcloud dataflow flex-template run JOB_NAME \
        --project=PROJECT_ID \
        --region=REGION_NAME \
        --enable-streaming-engine \
        --template-file-gcs-location=gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_BigQuery \
        --parameters \
    inputFilePattern=GCS_FILE_PATH,\
    gcsPubSubSubscription=GCS_SUBSCRIPTION_NAME,\
    outputStagingDatasetTemplate=BIGQUERY_DATASET,\
    outputDatasetTemplate=BIGQUERY_DATASET,\
    outputStagingTableNameTemplate=BIGQUERY_TABLE,\
    outputTableNameTemplate=BIGQUERY_TABLE_log
      

    更改下列內容:

    • PROJECT_ID:您要執行 Dataflow 工作的 Google Cloud 專案 ID
    • JOB_NAME:您選擇的不重複工作名稱
    • REGION_NAME:您要部署 Dataflow 工作的區域,例如 us-central1
    • VERSION: the version of the template that you want to use

      You can use the following values:

      • latest to use the latest version of the template, which is available in the non-dated parent folder in the bucket— gs://dataflow-templates/latest/
      • the version name, like 2023-09-12-00_RC00, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket— gs://dataflow-templates/
    • GCS_FILE_PATH:Datastream 資料的 Cloud Storage 路徑。例如:gs://bucket/path/to/data/
    • GCS_SUBSCRIPTION_NAME:要讀取變更檔案的 Pub/Sub 訂閱項目。例如:projects/my-project-id/subscriptions/my-subscription-id。
    • BIGQUERY_DATASET:BigQuery 資料集名稱。
    • BIGQUERY_TABLE:BigQuery 資料表範本。例如:{_metadata_schema}_{_metadata_table}_log

    API

    如要使用 REST API 執行範本,請傳送 HTTP POST 要求。如要進一步瞭解 API 和授權範圍,請參閱 projects.templates.launch。

    POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
    {
       "launch_parameter": {
          "jobName": "JOB_NAME",
          "parameters": {
    
              "inputFilePattern": "GCS_FILE_PATH",
              "gcsPubSubSubscription": "GCS_SUBSCRIPTION_NAME",
              "outputStagingDatasetTemplate": "BIGQUERY_DATASET",
              "outputDatasetTemplate": "BIGQUERY_DATASET",
              "outputStagingTableNameTemplate": "BIGQUERY_TABLE",
              "outputTableNameTemplate": "BIGQUERY_TABLE_log"
          },
          "containerSpecGcsPath": "gs://dataflow-templates/VERSION/flex/Cloud_Datastream_to_BigQuery",
       }
    }
      

    更改下列內容:

    • PROJECT_ID:您要執行 Dataflow 工作的 Google Cloud 專案 ID
    • JOB_NAME:您選擇的不重複工作名稱
    • LOCATION:您要部署 Dataflow 工作的區域,例如 us-central1
    • VERSION: the version of the template that you want to use

      You can use the following values:

      • latest to use the latest version of the template, which is available in the non-dated parent folder in the bucket— gs://dataflow-templates/latest/
      • the version name, like 2023-09-12-00_RC00, to use a specific version of the template, which can be found nested in the respective dated parent folder in the bucket— gs://dataflow-templates/
    • GCS_FILE_PATH:Datastream 資料的 Cloud Storage 路徑。例如:gs://bucket/path/to/data/
    • GCS_SUBSCRIPTION_NAME:要讀取變更檔案的 Pub/Sub 訂閱項目。例如:projects/my-project-id/subscriptions/my-subscription-id。
    • BIGQUERY_DATASET:BigQuery 資料集名稱。
    • BIGQUERY_TABLE:BigQuery 資料表範本。例如:{_metadata_schema}_{_metadata_table}_log

    後續步驟