Dataflow 管理的 I/O

Dataflow 可透過代管 I/O 管理 Apache Beam 管道中使用的特定 I/O 連接器。代管 I/O 可簡化管道管理作業,整合支援的來源和接收器。

代管 I/O 由兩個元件組成,兩者會協同運作:

  • Apache Beam 轉換,提供用於建立 I/O 連接器 (來源和接收器) 的通用 API。

  • Dataflow 服務會代您管理這些 I/O 連接器,包括獨立於 Apache Beam 版本升級連接器。

代管 I/O 的優點包括:

  • 自動升級。Dataflow 會自動升級管道中的代管 I/O 連接器。這表示管道會收到這些連接器的安全性修正、效能改善和修正錯誤,無須變更任何程式碼。詳情請參閱「自動升級」。

  • 一致的 API。傳統上,Apache Beam 中的 I/O 連接器具有不同的 API,且每個連接器的設定方式都不同。Managed I/O 提供單一設定 API,使用鍵/值屬性,因此管道程式碼更簡單且一致。詳情請參閱「Configuration API」。

需求條件

  • 下列 SDK 支援代管 I/O:

    • Java 適用的 Apache Beam SDK 2.58.0 以上版本。
    • Apache Beam SDK for Python 2.61.0 以上版本。
  • 後端服務需要 Dataflow Runner v2。如果未啟用 Runner v2,管道仍會執行,但無法享有代管 I/O 服務的好處。

自動升級

Dataflow 管道搭配代管 I/O 連接器時,會自動使用最新可靠版本的連接器。自動升級會在工作生命週期的下列時間點進行:

  • 工作提交。提交批次或串流工作時,Dataflow 會使用最新版代管 I/O 連接器,該連接器已通過測試且運作良好。

  • 滾動式升級。如果是串流工作,Dataflow 會在有新版本時,升級執行中管道的代管 I/O 連接器。您不必手動更新連接器或管道的 Apache Beam 版本。

    根據預設,滾動式升級會在 30 天內進行,也就是大約每 30 天執行一次升級。您可以調整維護期間,或針對個別工作停用滾動式升級。詳情請參閱「設定滾動式升級時間範圍」。

    升級前一週,Dataflow 會將通知訊息寫入工作訊息記錄。

  • 替換工作。如果是串流工作,Dataflow 會在您啟動替換工作時檢查更新,並自動使用最新的已知良好版本。即使您未變更替換工作中的任何程式碼,Dataflow 也會執行這項檢查。

下圖顯示升級程序。使用者使用 SDK 版本 X 建立 Apache Beam 管道。Dataflow 會將代管 I/O 版本升級至最新支援版本。升級作業會在使用者提交工作、滾動升級時間範圍結束後,或使用者提交替換工作時進行。

圖表:代管 I/O 升級程序。

升級程序會使第一個使用代管 I/O 的工作 (每個專案) 啟動時間增加約兩分鐘,後續工作則增加約半分鐘。如果是滾動式升級,Dataflow 服務會啟動替換工作。這可能會導致管道暫時停機,因為現有的 worker 集區會關閉,新的 worker 集區會啟動。如要查看代管 I/O 作業的狀態,請尋找包含「Managed Transform(s)」字串的記錄項目。

設定滾動式升級時間範圍

如要指定串流 Dataflow 工作的升級時間範圍,請將 managed_transforms_rolling_upgrade_window 服務選項設為天數。值必須介於 10 到 90 天之間 (含)。

Java

--dataflowServiceOptions=managed_transforms_rolling_upgrade_window=DAYS

Python

--dataflow_service_options=managed_transforms_rolling_upgrade_window=DAYS

gcloud

使用 gcloud dataflow jobs run 指令,並加上 additional-experiments 選項。如果使用 Flex 範本,且該範本採用代管 I/O,請使用 gcloud dataflow flex-template run 指令。

--additional-experiments=managed_transforms_rolling_upgrade_window=DAYS

如要停用滾動式升級,請將 managed_transforms_rolling_upgrade_window 服務選項設為 never。您仍可啟動替換工作來觸發更新。

Java

--dataflowServiceOptions=managed_transforms_rolling_upgrade_window=never

Python

--dataflow_service_options=managed_transforms_rolling_upgrade_window=never

Go

--dataflow_service_options=managed_transforms_rolling_upgrade_window=never

gcloud

使用 gcloud dataflow jobs run 指令,並加上 additional-experiments 選項。如果使用 Flex 範本,請使用 gcloud dataflow flex-template run 指令。

--additional-experiments=managed_transforms_rolling_upgrade_window=never

Configuration API

代管 I/O 是全包式 Apache Beam 轉換,提供一致的 API 來設定來源和接收器。

Java

如要建立 Managed I/O 支援的任何來源或接收器,請使用 Managed 類別。指定要例項化的來源或接收器,並傳入一組設定參數,如下所示:

Map config = ImmutableMap.<String, Object>builder()
    .put("config1", "abc")
    .put("config2", 1);

pipeline.apply(Managed.read(/*Which source to read*/).withConfig(config))
    .getSinglePCollection();

您也可以透過 YAML 檔案傳遞設定參數。如需完整的程式碼範例,請參閱「從 Apache Iceberg 讀取」。

Python

匯入 apache_beam.transforms.managed 模組,並呼叫 managed.Read 或 managed.Write 方法。指定要例項化的來源或接收器,並傳入一組設定參數,如下所示:

pipeline
| beam.managed.Read(
    beam.managed.SOURCE, # Example: beam.managed.KAFKA
    config={
      "config1": "abc",
      "config2": 1
    }
)

您也可以透過 YAML 檔案傳遞設定參數。如需完整的程式碼範例,請參閱「從 Apache Kafka 讀取」。

動態目的地

對於某些接收器,代管 I/O 連接器可以根據傳入記錄中的欄位值,動態選取目的地。

如要使用動態目的地,請提供目的地的範本字串。範本字串可包含大括號內的欄位名稱,例如 "tables.{field1}"。在執行階段,連接器會替換每筆傳入記錄的欄位值,以判斷該記錄的目的地。

舉例來說,假設資料中有一個名為 airport 的欄位。您可以將目的地設為 "flights.{airport}"。如果 airport=SFO,記錄會寫入 flights.SFO。如果是巢狀欄位,請使用點標記法。例如:{top.middle.nested}。

如需瞭解如何使用動態目的地的程式碼範例,請參閱「使用動態目的地寫入」。

篩選

您可能需要在特定欄位寫入目的地資料表前,先篩除這些欄位。如果接收器支援動態目的地,您可以使用 drop、keep 或 only 參數。這些參數可讓您在輸入記錄中加入目的地中繼資料,而不必將中繼資料寫入目的地。

您最多可以為特定接收器設定其中一個參數。

設定參數 資料類型 說明
drop 字串清單 寫入目的地前要捨棄的欄位名稱清單。
keep 字串清單 寫入目的地時要保留的欄位名稱清單。其他欄位則會捨棄。
only 字串 寫入目的地時,要用做頂層記錄的單一欄位名稱。其他欄位都會捨棄。這個欄位必須是資料列類型。

支援的來源和接收器

代管 I/O 支援下列來源和接收器。

詳情請參閱 Apache Beam 說明文件中的「代管 I/O 連接器」。