Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

Dataflow 範本

您可以使用 Dataflow 範本封裝 Dataflow 管道來用於部署。任何具備適當權限的使用者，都能使用範本部署封裝的管道。您可以建立自訂 Dataflow 範本，Google 也提供常見情境適用的預建範本。

優點

相較於直接將管道部署至 Dataflow，範本有幾項優點：

範本可將管道設計與部署作業分開。舉例來說，開發人員可以建立範本，資料科學家則可在日後部署範本。
範本可以包含參數，讓您在部署範本時自訂管道。
您可以使用 Google Cloud 控制台、Google Cloud CLI 或 REST API 呼叫部署範本。您不需要在本機電腦上安裝開發環境或任何管道依附元件。
範本是程式碼構件，可儲存在原始碼控管存放區，並用於持續整合 (CI/CD) 管道。

Google 提供的範本

Google 提供多種預先建構的開放原始碼 Dataflow 範本，可用於常見情境。如要進一步瞭解可用的範本，請參閱「Google 提供的範本」。

比較 Flex 範本和傳統範本

Dataflow 支援兩種範本：Flex 範本 (較新) 和傳統範本。如要建立新的 Dataflow 範本，建議您建立 Flex 範本。

使用 Flex 範本時，管道會封裝為 Artifact Registry 中的 Docker 映像檔，並在 Cloud Storage 中附上範本規格檔案。範本規格包含指向 Docker 映像檔的指標。執行範本時，Dataflow 服務會啟動啟動器 VM、提取 Docker 映像檔，並執行管道。執行圖會根據使用者提供的執行階段參數動態建構。如要透過 API 啟動使用 Flex 範本的工作，請使用 projects.locations.flexTemplates.launch 方法。

傳統範本包含 Dataflow 工作圖的 JSON 序列化。管道的程式碼必須將所有執行階段參數包裝在 ValueProvider 介面中。使用者可以透過這個介面，在部署範本時指定參數值。如要透過 API 使用傳統範本，請參閱 projects.locations.templates API 參考文件。

Flex 範本比傳統範本更具優勢，包括：

與傳統範本不同，Flex 範本不需要 ValueProvider 介面來輸入參數。並非所有 Dataflow 來源和接收器都支援 ValueProvider。
傳統範本的工作圖表是靜態的，Flex 範本則可動態建構工作圖表。例如，範本可能會根據輸入參數選取不同的 I/O 連接器。
Flex 範本可在建構管道期間，對虛擬機器 (VM) 執行預先處理作業。例如，它可能會驗證輸入參數值。

範本工作流程

使用 Dataflow 範本時，大致上會涉及下列步驟：

開發人員會設定開發環境並開發管道。環境包含 Apache Beam SDK 和其他依附元件。
視範本類型 (Flex 或傳統) 而定：
- 如果是 Flex 範本，開發人員會將管道封裝成 Docker 映像檔、將映像檔推送至 Artifact Registry，並將範本規格檔案上傳至 Cloud Storage。
- 如果是傳統範本，開發人員會執行管道、建立範本檔案，並將範本暫存至 Cloud Storage。
其他使用者則向 Dataflow 服務提交要求，以執行範本。
Dataflow 會根據範本建立管道。管道最多可能需要五到七分鐘才會開始執行。

檢查及稽核範本工作

使用 REST API 或 Google Cloud CLI，以程式輔助方式稽核執行中或歷來的 Dataflow 範本工作時，預設檢視畫面為摘要檢視畫面 (JOB_VIEW_SUMMARY)。摘要檢視畫面會省略管道執行詳細資料、範本中繼資料和 SDK 管道選項。如要擷取範本詳細資料和環境選項，您必須明確要求完整工作檢視畫面。

如要檢查工作的範本詳細資料，請使用下列其中一種方法：

gcloud CLI

如要擷取完整工作說明 (包括範本詳細資料)，請執行 gcloud dataflow jobs describe 指令並加上 --full 旗標：

使用下列任何指令資料前，請先替換以下項目：

REGION：執行工作的 Dataflow 區域。
JOB_ID：Dataflow 工作的 ID。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (PowerShell)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

Windows (cmd.exe)

gcloud dataflow jobs describe JOB_ID --full --region=REGION

您應該會收到類似以下的回應：

environment:
  sdkPipelineOptions:
    options:
      templateLocation: gs://BUCKET_NAME/templates/TEMPLATE_NAME
id: JOB_ID
name: JOB_NAME
type: JOB_TYPE_BATCH

REST

如要擷取完整的工作資源 (包括範本詳細資料)，請使用 view=JOB_VIEW_ALL 查詢參數，將 HTTP GET 要求傳送至 projects.locations.jobs.get 方法：

使用任何要求資料之前，請先修改下列項目的值：

PROJECT_ID：您的 Google Cloud 專案 ID。
REGION：執行工作的 Dataflow 區域。
JOB_ID：Dataflow 工作的 ID。

HTTP 方法和網址：

GET https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL

如要傳送要求，請選擇以下其中一個選項：

curl

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login 透過使用者帳戶登入 gcloud CLI，或是使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL"

PowerShell

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/REGION/jobs/JOB_ID?view=JOB_VIEW_ALL" | Select-Object -Expand Content

您應該會收到如下的 JSON 回覆：

{
  "id": "JOB_ID",
  "name": "JOB_NAME",
  "type": "JOB_TYPE_BATCH",
  "environment": {
    "sdkPipelineOptions": {
      "options": {
        "templateLocation": "gs://BUCKET_NAME/templates/TEMPLATE_NAME"
      }
    }
  }
}

識別範本類型

回應酬載會因工作是透過 Google 提供的範本或自訂範本建立而異：

Google 提供的範本：Dataflow 會自動將預先定義的標籤附加至工作資源：
- goog-dataflow-provided-template-name：範本名稱。
- goog-dataflow-provided-template-type：範本類型，flex 或 legacy (傳統)。
- goog-dataflow-provided-template-version：範本的發布版本。
自訂範本：自訂範本工作沒有 goog-dataflow-provided-* 標籤。Flex 和傳統範本工作都會在 environment.sdkPipelineOptions 中填入 templateLocation 選項。如要判斷沒有標籤的自訂工作範本類型，請檢查完整工作回應 (JOB_VIEW_ALL) 中的下列欄位：
- 傳統範本：templateLocation 欄位會直接指向 Cloud Storage 中暫存的範本 JSON 檔案。例如，路徑類似 gs://BUCKET_NAME/templates/TEMPLATE_NAME。傳統範本工作沒有容器啟動器映像檔設定。
- Flex 範本：Flex 範本工作會從啟動器容器映像檔執行。在 environment 物件下，Flex 範本工作包含啟動器容器規格和參數 (例如 flexResourceLimits)。此外，啟動期間產生的暫存 templateLocation Cloud Storage 路徑包含工作 ID。

最佳做法：在啟動期間附加使用者標籤

由於以程式輔助方式區分自訂範本類型需要擷取並剖析完整的 JOB_VIEW_ALL 環境選項，因此建議您在啟動範本工作時附加描述性使用者標籤。例如，附加 template-type: flex 或 template-type: classic 等標籤。

使用者標籤會顯示在預設摘要檢視畫面 (JOB_VIEW_SUMMARY) 和工作清單作業中。使用者標籤可讓您在專案中有效率地篩選、搜尋及稽核範本工作，不必擷取每項工作的完整執行酬載。

如要在啟動範本時附加標籤，請使用下列方法：

如要在 gcloud CLI 中使用 Flex 範本，請在 gcloud dataflow flex-template run 指令中使用 --additional-user-labels 旗標。
如要在 gcloud CLI 中使用傳統範本，請在 gcloud dataflow jobs run 指令中使用 --labels 旗標。
使用 REST API 時，請在啟動要求的要求主體中加入 labels 鍵/值對應。

設定 IAM 權限

Dataflow 工作 (包括從範本執行的工作) 會使用兩個 IAM 服務帳戶：

Dataflow 服務會使用 Dataflow 服務帳戶來操控 Google Cloud 資源，例如建立 VM。
Dataflow worker VM 會使用 worker 服務帳戶存取管道的檔案和其他資源。這個服務帳戶必須能存取管道工作參照的所有資源，包括範本使用的來源和接收器。詳情請參閱「存取 Google Cloud 資源」。

請確保這兩個服務帳戶具備適當角色。詳情請參閱「Dataflow 安全性與權限」。

如果貴組織使用主體存取權邊界 (PAB) 政策，主體 (例如使用者或服務帳戶) 可能無法查看及執行 Google 提供的範本。如需更多資訊和解決方案，請參閱「使用主體存取邊界政策存取 Google 提供的範本」。

Apache Beam SDK 版本需求

如要建立自己的範本，請確認您的 Apache Beam SDK 版本支援範本建立功能。

Java

如要使用 Apache Beam SDK 2.x for Java 建立範本，您必須使用 2.0.0-beta3 以上版本。

Python

如要使用 Apache Beam SDK 2.x for Python 建立範本，您必須具備 2.0.0 以上版本。

如要使用 Google Cloud CLI 執行範本，您必須具備 Google Cloud CLI 138.0.0 以上版本。

擴充範本

您可以擴充開放原始碼 Dataflow 範本，自行建構範本。舉例來說，如果範本使用固定時間範圍，時間範圍外的資料可能會遭到捨棄。為避免這種情況，請以範本程式碼為基礎，並修改程式碼來叫用 .withAllowedLateness 作業。

Dataflow 範本 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

優點

Google 提供的範本

比較 Flex 範本和傳統範本

範本工作流程

檢查及稽核範本工作

gcloud CLI

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl

PowerShell

識別範本類型

最佳做法：在啟動期間附加使用者標籤

設定 IAM 權限

Apache Beam SDK 版本需求

Java

Python

擴充範本

後續步驟

Dataflow 範本