使用 Pub/Sub 訊息觸發工作流程 (gcloud CLI)

標準

本快速入門導覽課程說明如何使用 Eventarc 觸發條件執行工作流程，並透過 Pub/Sub 接收事件。觸發程序會將透過 Pub/Sub 傳送的事件做為執行階段引數，傳遞至目的地工作流程，藉此執行工作流程。

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

使用 Workflows 建立及部署工作流程，解碼及傳回 Pub/Sub 訊息。
建立 Eventarc 觸發條件，將 Pub/Sub 主題連結至 Workflows 事件接收器。
將訊息發布至 Pub/Sub 主題，產生事件。這個事件會以執行階段引數的形式傳遞至目的地工作流程。
查看工作流程執行後產生的 Pub/Sub 訊息。

事前準備

請要求將專案加入 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 。

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

啟用 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

設定本教學課程中使用的設定變數：

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

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

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

如要取得完成本快速入門導覽課程所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- Eventarc 管理員 (roles/eventarc.admin)
- 記錄檔檢視存取者 (roles/logging.viewAccessor)
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- Pub/Sub Publisher (roles/pubsub.publisher)
- 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
- 服務帳戶使用者 (roles/iam.serviceAccountUser)
- 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
- 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 查看變更會造成的影響，然後授予及撤銷適當的角色。

將專案的工作流程叫用者角色 (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

如果您是在 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
```

建立及部署工作流程

建立及部署工作流程，當發布至 Pub/Sub 主題的訊息以 HTTP 要求觸發工作流程時，系統就會執行該工作流程。

開啟終端機或 Cloud Shell。
在主目錄中，建立名為 myFirstWorkflow.yaml 或 myFirstWorkflow.json 的新檔案。

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

YAML

main:
  params: [event]
  steps:
    - decode_pubsub_message:
        assign:
           - base64: ${base64.decode(event.data.message.data)}
           - message: ${text.decode(base64)}
    - return_pubsub_message:
        return: ${message}

JSON

{
  "main": {
    "params": [
      "event"
    ],
    "steps": [
      {
        "decode_pubsub_message": {
          "assign": [
            {
              "base64": "${base64.decode(event.data.message.data)}"
            },
            {
              "message": "${text.decode(base64)}"
            }
          ]
        }
      },
      {
        "return_pubsub_message": {
          "return": "${message}"
        }
      }
    ]
  }
}

部署工作流程：

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

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

建立 Eventarc 觸發條件

訊息發布至 Pub/Sub 主題時，事件會觸發工作流程。

建立觸發條件，監聽 Pub/Sub 訊息：
新增 Pub/Sub 主題
gcloud eventarc triggers create events-pubsub-trigger \ --destination-workflow=${MY_WORKFLOW} \ --destination-workflow-location=${WORKFLOW_LOCATION} \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --service-account="PROJECT_NUMBER-compute@developer.gserviceaccount.com"
這會建立新的 Pub/Sub 主題，以及名為 events-pubsub-trigger 的觸發條件。
現有 Pub/Sub 主題
gcloud eventarc triggers create events-pubsub-trigger \ --destination-workflow=${MY_WORKFLOW} \ --destination-workflow-location=${WORKFLOW_LOCATION} \ --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \ --service-account="PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ --transport-topic=TOPIC_ID
將 TOPIC_ID 替換為現有 Pub/Sub 主題的 ID。

這會為現有的 Pub/Sub 主題建立名為 events-pubsub-trigger 的觸發條件。
注意：根據預設，為 Eventarc 建立的 Pub/Sub 訂閱項目會持續存在，不會過期。如要變更閒置時間長度，請參閱「訂閱屬性」。

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

確認觸發條件已成功建立：

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

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

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

產生及查看活動

將訊息發布至 Pub/Sub 主題，產生事件並觸發工作流程。產生的事件會以執行階段引數的形式傳遞至工作流程，而工作流程會傳回 Pub/Sub 訊息做為執行結果。請確認傳遞至工作流程的事件大小未超過 512 KB。

如果您為新的 Pub/Sub 主題建立觸發條件，請找出並設定建立的 Pub/Sub 主題做為環境變數：

export TOPIC_ID=$(basename $(gcloud eventarc triggers describe events-pubsub-trigger --format='value(transport.pubsub.topic)'))

如要觸發工作流程，請將訊息傳送至 Pub/Sub 主題：
```
gcloud pubsub topics publish $TOPIC_ID --message "Hello there"
```
產生的事件會以執行階段引數的形式傳遞至工作流程，並傳回「Hello there」訊息。

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

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-09-13T19:15:10.275677049Z
END_TIME: 2021-09-13T19:15:10.963136883Z
NAME: projects/606789101455/locations/us-central1/workflows/myFirstWorkflow/executions/a6319d9d-36a6-4117-904e-3d1118bdc90a
STATE: SUCCEEDED
START_TIME: 2021-09-13T17:28:51.492864252Z
END_TIME: 2021-09-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 替換為與 Pub/Sub 主題發布時間相符的工作流程執行作業 ID。輸出結果會與下列內容相似：

argument: [...]
endTime: '2021-09-13T17:28:47.301012152Z'
name: projects/1234567/locations/us-central1/workflows/myFirstWorkflow/executions/f72bc6d4-5ea0-4dfb-bb14-2dae82303120
result: 'Hello there'
startTime: '2021-09-13T17:28:51.492864252Z'
state: SUCCEEDED

確認 Pub/Sub 訊息發布時間 publish_time 與工作流程執行時間 startTime 相符。

恭喜！您已成功使用 Pub/Sub 主題產生事件，該事件使用 Eventarc 觸發了 Workflows 事件接收器。

清除所用資源

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

刪除您建立的觸發條件：

gcloud eventarc triggers delete events-pubsub-trigger

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

使用 Pub/Sub 訊息觸發工作流程 (gcloud CLI)

事前準備

所需權限

建立及部署工作流程

YAML

JSON

建立 Eventarc 觸發條件

新增 Pub/Sub 主題

現有 Pub/Sub 主題

產生及查看活動

清除所用資源

後續步驟