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 的工作 (每個專案) 啟動時間增加約兩分鐘,後續工作則增加約半分鐘。如果是滾動式升級,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 連接器」。