透過 Cloud Storage 的直接事件觸發 Workflows (gcloud CLI)

標準

本快速入門導覽課程說明如何使用 Eventarc 觸發條件執行工作流程，接收來自 Cloud Storage 的事件。

觸發條件會監聽 Cloud Storage bucket 中的物件建立事件，並將事件以執行階段引數的形式傳遞至目的地工作流程，藉此執行工作流程。

在本快速入門導覽課程中，您將：

建立 Cloud Storage bucket 做為事件來源。
使用 Workflows 建立及部署工作流程，以擷取及傳回儲存空間 bucket 的名稱和上傳檔案的名稱。
建立 Eventarc 觸發條件，將 Cloud Storage bucket 連結至 Workflows 事件接收器。
將文字檔案上傳至 Cloud Storage 值區，以便產生事件。這個事件會以執行階段引數的形式傳遞至目的地工作流程。
在工作流程執行後，查看相應 bucket 和文字檔案的名稱。

如要直接在 Google Cloud 控制台中，按照這項工作的逐步指南操作，請按一下「Guide me」(逐步引導)：

「Guide me」(逐步引導)

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 Google Cloud 環境中開發應用程式」。

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

安裝 Google Cloud CLI。

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

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

gcloud init

建立或選取 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 專案名稱。

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

安裝 Google Cloud CLI。

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

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

gcloud init

建立或選取 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 專案名稱。

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

啟用 Compute Engine、Eventarc、Pub/Sub 和 Workflows API。

gcloud services enable \
compute.googleapis.com \
eventarc.googleapis.com \
pubsub.googleapis.com \
workflows.googleapis.com \
workflowexecutions.googleapis.com

更新 gcloud 元件：
```
gcloud components update
```

登入帳戶：
```
gcloud auth login
```

設定環境變數

設定本快速入門導覽課程中使用的環境變數。

export PROJECT_ID=PROJECT_ID
export WORKFLOW_LOCATION=us-central1
export TRIGGER_LOCATION=us-central1
gcloud config set project ${PROJECT_ID}
gcloud config set workflows/location ${WORKFLOW_LOCATION}
gcloud config set eventarc/location ${TRIGGER_LOCATION}

您可以在 Google Cloud 控制台的「Welcome」(歡迎)頁面找到專案 ID。

設定服務帳戶

將必要權限授予本快速入門導覽中使用的服務帳戶。

如果您是專案建立者，系統會授予基本「擁有者」角色 (roles/owner)。根據預設，這個身分與存取權管理 (IAM) 角色包含完全存取大多數 Google Cloud資源所需的權限，因此您可以略過這個步驟。

如果您不是專案建立者，必須在專案中將必要權限授予適當的主體。舉例來說，主體可以是 Google 帳戶 (適用於使用者)，也可以是服務帳戶 (適用於應用程式和運算工作負載)。詳情請參閱活動目的地的「角色和權限」頁面。
所需權限

如要取得完成本快速入門導覽課程所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- Eventarc 管理員 (roles/eventarc.admin)
- 記錄檔檢視存取者 (roles/logging.viewAccessor)
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
- 服務帳戶使用者 (roles/iam.serviceAccountUser)
- 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
- 儲存空間管理員 (roles/storage.admin)
- Workflows 管理員 (roles/workflows.admin)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。
記下 Compute Engine 預設服務帳戶，因為您會將其附加至 Eventarc 觸發程序，代表觸發程序的身分進行測試。啟用或使用採用 Compute Engine 的服務後，系統會自動建立這個服務帳戶，電子郵件地址格式如下： Google Cloud
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
將 PROJECT_NUMBER 替換為 Google Cloud專案編號。您可以在 Google Cloud 控制台的「歡迎」頁面找到專案編號，也可以執行下列指令：
```
gcloud projects describe PROJECT_ID --format='value(projectNumber)'
```
在正式環境中，我們強烈建議建立新的服務帳戶，並授予一或多個包含最低必要權限的 IAM 角色，同時遵循最低權限原則。

注意：
iam.automaticIamGrantsForDefaultServiceAccounts 組織政策限制可防止系統自動將編輯者角色授予預設服務帳戶。如果組織是在 2024 年 5 月 3 日後建立，系統預設會強制執行這項限制。

強烈建議您強制執行這項限制，停用自動角色授予功能。停用此功能後，您必須決定要將哪些角色授予預設服務帳戶，然後自行授予這些角色。

如果預設服務帳戶已具備「編輯者」角色，建議您將「編輯者」角色替換為權限較少的角色。如要安全修改服務帳戶的角色，請使用 Policy Simulator 查看變更會造成的影響，然後授予及撤銷適當的角色。

將專案的Eventarc 事件接收者角色 (roles/eventarc.eventReceiver) 授予 Compute Engine 預設服務帳戶，以便 Eventarc 觸發條件接收事件供應商的事件。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/eventarc.eventReceiver

將專案的工作流程叫用者角色 (roles/workflows.invoker) 授予 Compute Engine 預設服務帳戶，讓該帳戶有權觸發工作流程執行作業。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/workflows.invoker

將專案的「記錄檔寫入者」角色 (roles/logging.logWriter) 授予 Compute Engine 預設服務帳戶，以便工作流程將記錄傳送至 Cloud Logging。

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/logging.logWriter

建立 Cloud Storage 直接事件的觸發條件前，請先將 Pub/Sub 發布者角色 (roles/pubsub.publisher) 授予 Cloud Storage 服務代理：

SERVICE_ACCOUNT="$(gcloud storage service-agent --project=PROJECT_ID)"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:${SERVICE_ACCOUNT}" \
    --role='roles/pubsub.publisher'

如果您是在 2021 年 4 月 8 日當天或之前啟用 Cloud Pub/Sub 服務代理，請將服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予服務代理，以支援已驗證的 Pub/Sub 推送要求。否則，系統會預設授予這個角色：
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
```

建立 Cloud Storage 值區

建立要用做事件來源的 Cloud Storage bucket：

  gcloud storage buckets create gs://${PROJECT_ID}-bucket --location=us-central1

建立及部署工作流程

建立及部署工作流程，在 Cloud Storage bucket 中建立物件時，以 HTTP 要求觸發工作流程。

在主目錄中，建立名為 myEventWorkflow.yaml 或 myEventWorkflow.json 的新檔案。

複製以下內容並貼到新檔案中，然後儲存檔案：

YAML

  main:
    params: [event]
    steps:
        - log_event:
            call: sys.log
            args:
                text: ${event}
                severity: INFO
        - extract_bucket_object:
            assign:
            - bucket: ${event.data.bucket}
            - object: ${event.data.name}
        - return_bucket_object:
                return:
                    bucket: ${bucket}
                    object: ${object}

JSON

{
"main": {
"params": [
  "event"
],
"steps": [
  {
    "log_event": {
      "call": "sys.log",
      "args": {
        "text": "${event}",
        "severity": "INFO"
      }
    }
  },
  {
    "extract_bucket_object": {
      "assign": [
        {
          "bucket": "${event.data.bucket}"
        },
        {
          "object": "${event.data.name}"
        }
      ]
    }
  },
  {
    "return_bucket_object": {
      "return": {
        "bucket": "${bucket}",
        "object": "${object}"
      }
    }
  }
]
}
}

部署工作流程：

export MY_WORKFLOW=myEventWorkflow
gcloud workflows deploy ${MY_WORKFLOW} --source=myEventWorkflow.yaml

如果您複製了範例工作流程的 JSON 版本，請將 .yaml 替換為 .json。

建立 Eventarc 觸發條件

Eventarc 觸發條件會將 Cloud Storage bucket 中的事件傳送至 Workflows 目的地。

建立用來篩選 Cloud Storage 事件的觸發條件：
```
gcloud eventarc triggers create storage-events-trigger \
    --destination-workflow=${MY_WORKFLOW} \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=${PROJECT_ID}-bucket" \
    --service-account="PROJECT_NUMBER-compute@developer.gserviceaccount.com"
```
這項操作會建立名為 storage-events-trigger 的觸發條件。

請注意，在 Google Cloud 專案中首次建立 Eventarc 觸發條件時，Eventarc 服務代理程式的佈建作業可能會延遲。通常只要再次嘗試建立觸發條件，就能解決這個問題。詳情請參閱「權限遭拒錯誤」。

如要確認 storage-events-trigger 是否已建立妥當，請執行：

gcloud eventarc triggers describe storage-events-trigger --location=${TRIGGER_LOCATION}

輸出內容應與下方類似，列出建立時間和觸發位置：

createTime: '2021-10-14T15:15:43.872360951Z'
[...]
name: projects/PROJECT_ID/locations/us-central1/triggers/storage-events-trigger

產生及查看活動

如要產生事件，請將文字檔案上傳到 Cloud Storage：
```
echo "Hello World" > random.txt
gcloud storage cp random.txt gs://${PROJECT_ID}-bucket/random.txt
```
上傳作業會產生事件，並以執行階段引數的形式傳遞至工作流程，該工作流程會傳回儲存空間 bucket 和上傳檔案的名稱。

如要確認是否已觸發工作流程執行作業，請列出最近五次的執行作業：

gcloud workflows executions list ${MY_WORKFLOW} --limit=5

畫面會顯示類似以下的輸出內容，針對每個工作流程執行作業列出 NAME 和相當於 SUCCEEDED 的 STATE：

NAME: projects/606789101455/locations/us-central1/workflows/myFirstWorkflow/executions/8c02b8f1-8836-4a6d-99d9-fc321eb9668f
STATE: SUCCEEDED
START_TIME: 2021-10-13T03:38:03.019148617Z
END_TIME: 2021-10-13T03:38:03.249705805Z
NAME: projects/606789101455/locations/us-central1/workflows/myFirstWorkflow/executions/a6319d9d-36a6-4117-904e-3d1118bdc90a
STATE: SUCCEEDED
START_TIME: 2021-10-13T17:28:51.492864252Z
END_TIME: 2021-10-13T17:28:52.227212414Z

請注意，在上述範例的 NAME 欄位中，a6319d9d-36a6-4117-904e-3d1118bdc90a 是工作流程執行作業的 ID。複製執行 ID，這會在下一個步驟中用到。

如要查看執行狀態，請執行下列指令：

gcloud workflows executions describe WORKFLOW_EXECUTION_ID --workflow=${MY_WORKFLOW}

將 WORKFLOW_EXECUTION_ID 替換為與檔案上傳至 bucket 的時間相符的工作流程執行作業 ID。

輸出結果會與下列內容相似：

argument: [...]
name: projects/218898424763/locations/us-central1/workflows/myEventWorkflow/executions/86d2567b-0f1e-49b3-8b10-cdac5d0f6239
result: '{"bucket":"PROJECT_ID-bucket","object":"random.txt"}'
startTime: '2021-10-13T03:38:03.019148617Z'
state: SUCCEEDED

確認 Cloud Storage bucket 的更新時間 "timeCreated": "2021-10-13T03:38" 和工作流程執行的 startTime 是否相符。

恭喜！您已成功產生 Cloud Storage 事件，該事件使用 Eventarc 觸發了 Workflows 事件接收器。

清除所用資源

為了避免系統向您的 Google Cloud 帳戶收取本頁面所用資源的費用，請刪除含有這些資源的 Google Cloud 專案。

刪除您建立的工作流程：
```
gcloud workflows delete ${MY_WORKFLOW}
```
系統詢問您是否要繼續時，請輸入 y。

刪除儲存空間 bucket：

gcloud storage rm gs://${PROJECT_ID}-bucket/ --recursive

刪除在本教學課程中建立的觸發條件：

gcloud eventarc triggers delete storage-events-trigger

或者，您也可以刪除 Google Cloud 專案，以免產生費用。刪除 Google Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。
注意：刪除專案會造成以下結果：
- 專案中的所有內容都會遭到刪除。如果使用現有專案來進行本文中的任務，刪除專案將一併移除當中已完成的其他任務'。
- 自訂專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。
刪除 Google Cloud 專案：
```
gcloud projects delete PROJECT_ID
```