建構及執行彈性範本

---

Dataflow Flex 範本可讓您封裝 Dataflow 管道以進行部署。本教學課程說明如何建構 Dataflow 彈性範本，然後使用該範本執行 Dataflow 工作。

目標

• 建構 Dataflow Flex 範本。
• 使用範本執行 Dataflow 工作。

費用

在本文件中，您會使用 Google Cloud的下列計費元件：

• Dataflow
• Cloud Storage
• Artifact Registry
• Cloud Build

如要根據預測用量估算費用，請使用 Pricing Calculator。

初次使用 Google Cloud 的使用者可能符合免費試用資格。

完成本文所述工作後，您可以刪除已建立的資源，避免繼續計費。詳情請參閱清除所用資源一節。

事前準備

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Install the Google Cloud CLI.
如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。
如要初始化 gcloud CLI，請執行下列指令：
gcloud init
Create or select a Google Cloud project.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.
• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:
gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.
Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
Replace the following:
• PROJECT_ID: your project ID.
• USER_IDENTIFIER: the identifier for your user account—for example, [e-mail].
• ROLE: the IAM role that you grant to your user account.

Install the Google Cloud CLI.

如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

如要初始化 gcloud CLI，請執行下列指令：

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Dataflow, Compute Engine, Logging, Cloud Storage, Cloud Storage JSON, Resource Manager, Artifact Registry, and Cloud Build API:

gcloud services enable dataflow compute_component logging storage_component storage_api cloudresourcemanager.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

If you're using a local shell, then create local authentication credentials for your user account:

gcloud auth application-default login

You don't need to do this if you're using Cloud Shell.

If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

Grant roles to your user account. Run the following command once for each of the following IAM roles: roles/iam.serviceAccountUser

gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

Replace the following:

• PROJECT_ID: your project ID.
• USER_IDENTIFIER: the identifier for your user account—for example, [e-mail].
• ROLE: the IAM role that you grant to your user account.

1. 將角色授予 Compute Engine 預設服務帳戶。針對下列每個 IAM 角色，執行一次下列指令：

   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:[e-mail]" --role=SERVICE_ACCOUNT_ROLE

   更改下列內容：

   • PROJECT_ID：您的專案 ID
   • PROJECT_NUMBER 您的專案編號
   • SERVICE_ACCOUNT_ROLE：每個角色

準備環境

安裝 SDK 和開發環境的任何必要條件。

Java

1. 下載並安裝 Java Development Kit (JDK) 17 版。確認已設定 JAVA_HOME 環境變數，且指向您的 JDK 安裝。

2. 按照適用於您作業系統的 Maven 安裝指南，下載並安裝 Apache Maven。

Python

安裝 Apache Beam SDK for Python。

Go

請參閱 Go 的下載與安裝指南，下載並安裝適用於您作業系統的 Go。如要瞭解 Apache Beam 支援哪些 Go 執行階段環境，請參閱「Apache Beam 執行階段支援」。

下載程式碼範例。

Java

1. 複製 java-docs-samples 存放區。

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

2. 前往本教學課程的程式碼範例。

   cd java-docs-samples/dataflow/flex-templates/getting_started

3. 將 Java 專案建構為 Uber JAR 檔案。

   mvn clean package

   這個 Uber JAR 檔案內嵌所有依附元件。您可以將這個檔案當做獨立應用程式執行，不必依附其他程式庫。

Python

1. 複製 python-docs-samples 存放區。

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

2. 前往本教學課程的程式碼範例。

   cd python-docs-samples/dataflow/flex-templates/getting_started

Go

1. 複製 golang-samples 存放區。

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

2. 前往本教學課程的程式碼範例。

   cd golang-samples/dataflow/flex-templates/wordcount

3. 編譯 Go 二進位檔。

   CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o wordcount .

建立 Cloud Storage 值區

使用 gcloud storage buckets create 指令建立 Cloud Storage bucket：

gcloud storage buckets create gs://BUCKET_NAME

請將 BUCKET_NAME 改成 Cloud Storage bucket 的名稱。Cloud Storage bucket 名稱不得重複，且必須符合bucket 命名規定。

建立 Artifact Registry 存放區

建立 Artifact Registry 存放區，您將把範本的 Docker 容器映像檔推送至該處。

1. 使用 gcloud artifacts repositories create 指令建立新的 Artifact Registry 存放區。

   gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION

   更改下列內容：

   • REPOSITORY：存放區名稱。專案中每個存放區位置的存放區名稱不得重複。
   • LOCATION：存放區的區域或多區域位置。

2. 使用 gcloud auth configure-docker 指令，將 Docker 設定為驗證傳送至 Artifact Registry 的要求。這項指令會更新 Docker 設定，以便您連結 Artifact Registry 來推送映像檔。

   gcloud auth configure-docker LOCATION-docker.pkg.dev

Flex 範本也可以使用儲存在私人登錄檔中的映像檔。詳情請參閱「使用私人登錄檔中的映像檔」。

建構 Flex 範本

在本步驟中，您將使用 gcloud dataflow flex-template build 指令建構 Flex 範本。

彈性範本包含下列元件：

• 封裝管道程式碼的 Docker 容器映像檔。如果是 Java 和 Python 彈性範本，執行 gcloud dataflow flex-template build 指令時，Docker 映像檔會建構並推送至 Artifact Registry 存放區。
• 範本規格檔案。這個檔案是 JSON 文件，內含容器映像檔的位置，以及範本的中繼資料，例如管道參數。

GitHub 中的範例存放區包含 metadata.json 檔案。

• java-docs-samples 存放區
• python-docs-samples 存放區
• golang-samples 存放區

如要用額外的中繼資料擴充範本，可以建立自己的 metadata.json 檔案。

Java

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-java.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-java:latest" \
 --sdk-language "JAVA" \
 --flex-template-base-image JAVA17 \
 --metadata-file "metadata.json" \
 --jar "target/flex-template-getting-started-1.0.jar" \
 --env FLEX_TEMPLATE_JAVA_MAIN_CLASS="com.example.dataflow.FlexTemplateGettingStarted"

更改下列內容：

• BUCKET_NAME：您稍早建立的 Cloud Storage bucket 名稱
• LOCATION：位置
• PROJECT_ID：專案 ID Google Cloud
• REPOSITORY：您先前建立的 Artifact Registry 存放區名稱

Python

gcloud dataflow flex-template build gs://BUCKET_NAME/getting_started-py.json \
 --image-gcr-path "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/getting-started-python:latest" \
 --sdk-language "PYTHON" \
 --flex-template-base-image "PYTHON3" \
 --metadata-file "metadata.json" \
 --py-path "." \
 --env "FLEX_TEMPLATE_PYTHON_PY_FILE=getting_started.py" \
 --env "FLEX_TEMPLATE_PYTHON_REQUIREMENTS_FILE=requirements.txt"

更改下列內容：

• BUCKET_NAME：您稍早建立的 Cloud Storage bucket 名稱
• LOCATION：位置
• PROJECT_ID：專案 ID Google Cloud
• REPOSITORY：您先前建立的 Artifact Registry 存放區名稱

Go

1. 使用 gcloud builds submit 指令，透過 Cloud Build 和 Dockerfile 建構 Docker 映像檔。這個指令會建構檔案，並推送至 Artifact Registry 存放區。

   gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest .

   更改下列內容：

   • LOCATION：位置
   • PROJECT_ID：專案 ID Google Cloud
   • REPOSITORY：您先前建立的 Artifact Registry 存放區名稱

2. 使用 gcloud dataflow flex-template build 指令，在 Cloud Storage bucket 中建立名為 wordcount-go.json 的彈性範本。

   gcloud dataflow flex-template build gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json \
     --image "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/dataflow/wordcount-go:latest" \
     --sdk-language "GO" \
     --metadata-file "metadata.json"

   請將 BUCKET_NAME 改成您稍早建立的 Cloud Storage bucket 名稱。

執行 Flex 範本

在這個步驟中，您將使用範本執行 Dataflow 工作。

Java

1. 使用 gcloud dataflow flex-template run 指令執行使用 Flex 範本的 Dataflow 工作。

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-java.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   更改下列內容：

   • BUCKET_NAME：您稍早建立的 Cloud Storage bucket 名稱
   • REGION：區域
   • LABELS：選用。附加至工作的標籤，格式為 <key1>=<val1>,<key2>=<val2>,...

2. 如要在Google Cloud 控制台中查看 Dataflow 工作的狀態，請前往 Dataflow 的「Jobs」(工作) 頁面。

   前往「Jobs」(工作) 頁面

如果工作順利執行，系統會將輸出內容寫入 Cloud Storage bucket 中名為 gs://BUCKET_NAME/output--00000-of-00001.txt 的檔案。

Python

1. 使用 gcloud dataflow flex-template run 指令執行使用 Flex 範本的 Dataflow 工作。

   gcloud dataflow flex-template run "getting-started-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/getting_started-py.json" \
    --parameters output="gs://BUCKET_NAME/output-" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   更改下列內容：

   • BUCKET_NAME：您稍早建立的 Cloud Storage bucket 名稱
   • REGION：區域
   • LABELS：選用。附加至工作的標籤，格式為 <key1>=<val1>,<key2>=<val2>,...

2. 如要在Google Cloud 控制台中查看 Dataflow 工作的狀態，請前往 Dataflow 的「Jobs」(工作) 頁面。

   前往「Jobs」(工作) 頁面

如果工作順利執行，系統會將輸出內容寫入 Cloud Storage bucket 中名為 gs://BUCKET_NAME/output--00000-of-00001.txt 的檔案。

Go

1. 使用 gcloud dataflow flex-template run 指令執行使用 Flex 範本的 Dataflow 工作。

   gcloud dataflow flex-template run "wordcount-go-`date +%Y%m%d-%H%M%S`" \
    --template-file-gcs-location "gs://BUCKET_NAME/samples/dataflow/templates/wordcount-go.json" \
    --parameters output="gs://BUCKET_NAME/samples/dataflow/templates/counts.txt" \
    --additional-user-labels "LABELS" \
    --region "REGION"

   更改下列內容：

   • BUCKET_NAME：您稍早建立的 Cloud Storage bucket 名稱
   • REGION：區域
   • LABELS：選用。附加至工作的標籤，格式為 <key1>=<val1>,<key2>=<val2>,...

2. 如要在Google Cloud 控制台中查看 Dataflow 工作的狀態，請前往 Dataflow 的「Jobs」(工作) 頁面。

   前往「Jobs」(工作) 頁面

如果工作順利執行，系統會將輸出內容寫入 Cloud Storage bucket 中名為 gs://BUCKET_NAME/samples/dataflow/templates/count.txt 的檔案。

注意： 如果工作無法執行並顯示錯誤訊息 A Timeout in polling error message，請參閱「排解彈性範本逾時問題」。

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程中所用資源的相關費用，請刪除含有該項資源的專案，或者保留專案但刪除個別資源。

刪除專案

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。 如果您使用現有專案來進行本文中的工作，刪除專案將一併刪除其中已完成的所有工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

刪除個別資源

1. 刪除 Cloud Storage 值區和值區中的所有物件。

   gcloud storage rm gs://BUCKET_NAME --recursive

2. 刪除 Artifact Registry 存放區。

   gcloud artifacts repositories delete REPOSITORY \
       --location=LOCATION

3. 撤銷您授予 Compute Engine 預設服務帳戶的角色。針對下列每個 IAM 角色，執行一次下列指令：
   • roles/dataflow.admin
   • roles/dataflow.worker
   • roles/storage.objectAdmin
   • roles/artifactregistry.writer

   gcloud projects remove-iam-policy-binding PROJECT_ID \
       --member=serviceAccount:[e-mail] \
       --role=SERVICE_ACCOUNT_ROLE

4. Optional: Revoke the authentication credentials that you created, and delete the local credential file.

   gcloud auth application-default revoke

5. Optional: Revoke credentials from the gcloud CLI.

   gcloud auth revoke

後續步驟

• 瞭解如何設定 Flex 範本。
• 請參閱 Google 提供的範本清單。