建構並執行範例 Flex 範本

本教學課程著重於 Flex 範本，說明如何在 Dataflow 中建構及執行容器化資料管道。您將瞭解如何使用範例 Flex 範本，將管道封裝起來，以便有效率地部署。

目標

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

費用

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

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

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

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

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  2. 安裝 Google Cloud CLI。

  3. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  4. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  5. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  6. 確認專案已啟用計費功能 Google Cloud 。

  7. 啟用 Dataflow、Compute Engine、Logging、Cloud Storage、Cloud Storage JSON、Resource Manager 和 Artifact Registry API：

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

  8. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

    gcloud auth application-default login

    如果您使用 Cloud Shell，則不需要執行這項操作。

    如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

  9. 將角色授予使用者帳戶。針對下列每個 IAM 角色，執行一次下列指令： roles/iam.serviceAccountUser 

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

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • USER_IDENTIFIER：使用者帳戶的 ID。 例如：myemail@example.com。
    • ROLE：授予使用者帳戶的 IAM 角色。

  10. 安裝 Google Cloud CLI。

  11. 若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  12. 執行下列指令，初始化 gcloud CLI：

    gcloud init

  13. 建立或選取 Google Cloud 專案。

    選取或建立專案所需的角色

    • 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
    • 建立專案：如要建立專案，您需要具備專案建立者角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

    • 建立 Google Cloud 專案：

      gcloud projects create PROJECT_ID

      將 PROJECT_ID 替換為您要建立的 Google Cloud 專案名稱。

    • 選取您建立的 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為 Google Cloud 專案名稱。

  14. 確認專案已啟用計費功能 Google Cloud 。

  15. 啟用 Dataflow、Compute Engine、Logging、Cloud Storage、Cloud Storage JSON、Resource Manager 和 Artifact Registry API：

    啟用 API 時所需的角色

    如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

  16. 如果您使用本機殼層，請為使用者帳戶建立本機驗證憑證： 

    gcloud auth application-default login

    如果您使用 Cloud Shell，則不需要執行這項操作。

    如果系統傳回驗證錯誤，且您使用外部識別資訊提供者 (IdP)，請確認您已 使用聯合身分登入 gcloud CLI。

  17. 將角色授予使用者帳戶。針對下列每個 IAM 角色，執行一次下列指令： roles/iam.serviceAccountUser 

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

    更改下列內容：

    • PROJECT_ID：專案 ID。
    • USER_IDENTIFIER：使用者帳戶的 ID。 例如：myemail@example.com。
    • ROLE：授予使用者帳戶的 IAM 角色。
    18.

  18. 將角色授予 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:PROJECT_NUMBER-compute@developer.gserviceaccount.com" --role=SERVICE_ACCOUNT_ROLE

    更改下列內容：

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

準備 Flex 範本環境

安裝 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 bucket

使用 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 範本也可以使用儲存在私人登錄檔中的映像檔。詳情請參閱「使用私人登錄檔中的映像檔」。

建構 Dataflow Flex 範本

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

彈性範本包含下列元件：

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

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

如要用額外的中繼資料擴充範本，可以建立自己的 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： Google Cloud 專案 ID
  • 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： Google Cloud 專案 ID
  • REPOSITORY：您先前建立的 Artifact Registry 存放區名稱

Go

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

更改下列內容：

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

執行 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-" \
 --region "REGION"

    更改下列內容：

    • BUCKET_NAME：您先前建立的 Cloud Storage bucket 名稱
    • REGION：區域

  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-" \
 --region "REGION"

    更改下列內容：

    • BUCKET_NAME：您先前建立的 Cloud Storage bucket 名稱
    • REGION：區域

  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" \
 --region "REGION"

    更改下列內容：

    • BUCKET_NAME：您先前建立的 Cloud Storage bucket 名稱
    • REGION：區域

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

    前往「Jobs」(工作) 頁面

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

如果工作無法執行並顯示下列錯誤訊息，請參閱「疑難排解 Flex 範本逾時」。

A Timeout in polling error message

清除所用資源

為避免因為本教學課程所用資源，導致系統向 Google Cloud 收取費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

    刪除 Google Cloud 專案：

    gcloud projects delete PROJECT_ID

刪除個別資源

  1. 刪除 Cloud Storage bucket 和 bucket 中的所有物件。 
    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:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=SERVICE_ACCOUNT_ROLE

  4. 選用：撤銷您建立的驗證憑證，並刪除本機憑證檔案。

    gcloud auth application-default revoke

  5. 選用：從 gcloud CLI 撤銷憑證。 

    gcloud auth revoke

後續步驟