本頁面由 Cloud Translation API 翻譯而成。

在 Dataflow 中管理管道依附元件

許多 Apache Beam 管道都能使用預設的 Dataflow 執行階段環境執行。不過，部分資料處理用途適合使用其他程式庫或類別。在這種情況下，您可能需要管理管道依附元件。

以下列出您可能需要管理管道依附元件的幾個原因：

預設執行階段環境提供的依附元件不足以滿足您的用途。
預設依附元件發生版本衝突，或含有與管線程式碼不相容的類別和程式庫。
您需要將管道固定在特定程式庫版本。
您有一個 Python 管道，需要使用一組一致的依附元件執行。

管理依附元件的方式取決於管道是否使用 Java、Python 或 Go。

Java

不相容的類別和程式庫可能會導致 Java 依附元件問題。如果管線包含使用者專屬的程式碼和設定，程式碼就不能包含混合版本的程式庫。

Java 依附元件問題

如果管道有 Java 依附元件問題，可能會發生下列其中一項錯誤：

NoClassDefFoundError：如果執行階段無法使用整個類別，就會發生這項錯誤。
NoSuchMethodError：如果類別路徑中的類別使用的版本不含正確的方法，或是方法簽章已變更，就會發生這個錯誤。
NoSuchFieldError：如果類別路徑中的類別使用的版本沒有執行階段所需的欄位，就會發生這個錯誤。
FATAL ERROR：如果無法正確載入內建依附元件，就會發生這項錯誤。使用 uber JAR 檔案 (陰影) 時，請勿在同一個 JAR 檔案中加入使用簽章的程式庫，例如 Conscrypt。

依附元件管理

為簡化 Java 管道的依附元件管理，Apache Beam 使用 Bill of Materials (BOM) 構件。BOM 可協助依附元件管理工具選取相容的依附元件組合。詳情請參閱 Apache Beam 說明文件中的「Apache Beam SDK for Java dependencies」。

如要在管道中使用 BOM，並將其他依附元件明確新增至依附元件清單，請將下列資訊新增至 SDK 構件的 pom.xml 檔案。如要匯入正確的程式庫 BOM，請使用 beam-sdks-java-google-cloud-platform-bom。

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.apache.beam</groupId>
      <artifactId>beam-sdks-java-google-cloud-platform-bom</artifactId>
      <version>LATEST</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-core</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-runners-google-cloud-dataflow-java</artifactId>
  </dependency>
  <dependency>
    <groupId>org.apache.beam</groupId>
    <artifactId>beam-sdks-java-io-google-cloud-platform</artifactId>
  </dependency>
</dependencies>

beam-sdks-java-core 構件僅包含核心 SDK，您必須另外將其他依附元件 (如 I/O 和執行器) 手動新增至依附元件清單。

Python

使用 Apache Beam Python SDK 執行 Dataflow 工作時，在下列情況下，依附元件管理功能非常實用：

您的管道使用 Python Package Index (PiPy) 中的公開套件，且您想遠端提供這些套件。
您想建立可重現的環境。
為縮短啟動時間，您要避免在執行階段於工作人員上安裝依附元件。

定義 Python 管道依附元件

雖然您可以使用單一 Python 指令碼或筆記本編寫 Apache Beam 管道，但在 Python 生態系統中，軟體通常會以套件形式發布。為方便維護管道，如果管道程式碼跨越多個檔案，請將管道檔案分組為 Python 套件。

在套件的 setup.py 檔案中定義管道的依附元件。
使用 --setup_file 管道選項，將套件暫存至工作站。

遠端工作站啟動時，會安裝您的套件。如需範例，請參閱 Apache Beam GitHub 中的 juliaset。

如要將管道架構為 Python 套件，請按照下列步驟操作：

為專案建立 setup.py 檔案。在 setup.py 檔案中，加入 install_requires 引數，為管道指定最少的依附元件集。以下範例顯示基本的 setup.py 檔案。
```
import setuptools

setuptools.setup(
  name='PACKAGE_NAME',
  version='PACKAGE_VERSION',
  install_requires=[],
  packages=setuptools.find_packages(),
)
```
將 setup.py 檔案、主要工作流程檔案，以及含有其餘檔案的目錄，新增至專案的根目錄。這個檔案群組是管道的 Python 套件。檔案結構如下列範例所示：
```
root_dir/
  package_name/
    __init__.py
    my_pipeline_launcher.py
    my_custom_transforms.py
    ...other files...
  setup.py
  main.py
```
如要執行管道，請在提交環境中安裝套件。使用 --setup_file 管道選項，將套件暫存至工作站。例如：
```
python -m pip install -e .
python main.py --runner DataflowRunner --setup_file ./setup.py  <...other options...>
```

這些步驟可簡化管道程式碼維護作業，尤其是在程式碼大小和複雜度增加時。如要瞭解指定依附元件的其他方式，請參閱 Apache Beam 說明文件中的「管理 Python 管道依附元件」。

使用自訂容器控制執行階段環境

如要使用 Apache Beam Python SDK 執行管道，Dataflow 工作人員需要含有解譯器、Apache Beam SDK 和管道依附元件的 Python 環境。Docker 容器映像檔可提供適當的環境，執行管道程式碼。

每個 Apache Beam SDK 版本都會發布標準容器映像檔，這些映像檔包含 Apache Beam SDK 依附元件。詳情請參閱 Apache Beam 說明文件中的「Apache Beam SDK for Python dependencies」。

如果管道需要預設容器映像檔未包含的依附元件，就必須在執行階段安裝該依附元件。在執行階段安裝套件可能會造成下列後果：

由於依附元件解析、下載和安裝作業，工作人員啟動時間會增加。
管道必須連上網際網路才能執行。
依附元件中的軟體版本會導致非決定性。

為避免這些問題，請在自訂 Docker 容器映像檔中提供執行階段環境。使用預先安裝管道依附元件的自訂 Docker 容器映像檔，可享有下列優點：

確保每次啟動 Dataflow 工作時，管道執行階段環境都具有相同的依附元件集。
可控管管道的執行階段環境。
避免在啟動時解析可能耗時的依附元件。

使用自訂容器映像檔時，請參考下列指引：

請勿在自訂圖片中使用 :latest 標記。為建構版本加上日期、版本或專屬 ID 標記。如有需要，您可以在這個步驟還原為已知的有效設定。
使用與容器映像檔相容的啟動環境。如需使用自訂容器的更多指引，請參閱「建構容器映像檔」。

如要瞭解如何預先安裝 Python 依附元件，請參閱「預先安裝 Python 依附元件」。

使用 Dataflow 範本控管啟動環境

如果管道需要額外的依附元件，您可能需要在執行階段環境和啟動環境中安裝這些元件。啟動環境會執行管道的正式版。由於啟動環境必須與執行階段環境相容，因此請在這兩個環境中使用相同版本的依附元件。

如要建立可重現的容器化啟動環境，請使用 Dataflow Flex 範本。詳情請參閱「建構及執行 Flex 範本」。使用 Flex 範本時，請考慮下列因素：

如果將管道設定為套件，請在範本 Dockerfile 中安裝套件。如要設定 Flex 範本，請指定 FLEX_TEMPLATE_PYTHON_SETUP_FILE。詳情請參閱「設定必要的 Dockerfile 環境變數」。
如果管道使用自訂容器映像檔，請在啟動範本時提供該映像檔。詳情請參閱「使用自訂容器處理依附元件」。
如要建構 Dataflow Flex 範本 Docker 映像檔，請使用與基本映像檔相同的自訂容器映像檔。詳情請參閱「使用自訂容器映像檔」。

這種建構方式可讓啟動環境重現，並與執行階段環境相容。

如需採用這種做法的範例，請參閱 GitHub 的具有依附元件和自訂容器的管道彈性範本教學課程。

詳情請參閱 Apache Beam 說明文件中的「使啟動環境與執行階段環境相容」和「控管管道使用的依附元件」。

Go

使用 Apache Beam Go SDK 執行 Dataflow 工作時，系統會使用 Go 模組管理依附元件。下列檔案包含管道使用的預設編譯和執行階段依附元件：

https://raw.githubusercontent.com/apache/beam/vVERSION_NUMBER/sdks/go.sum

並將 VERSION_NUMBER 替換為您使用的 SDK 版本。

如要瞭解如何管理 Go 管道的依附元件，請參閱 Go 說明文件中的「管理依附元件」。

在 Dataflow 中管理管道依附元件 透過集合功能整理內容 你可以依據偏好儲存及分類內容。