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

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

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

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

事前準備

請要求將專案加入 Google Cloud 工作流程的私人預先發布版，確保您有權使用這項功能。

  1. 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.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Create or select a Google Cloud 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.

  6. Make sure that billing is enabled for your Google Cloud project.

  7. Install the Google Cloud CLI.

  8. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  9. To initialize the gcloud CLI, run the following command: 

    gcloud init

  10. Create or select a Google Cloud 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.

  11. Make sure that billing is enabled for your Google Cloud project.

  12. 更新 gcloud 元件： 
    gcloud components update
  13. 啟用 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
  14. 設定本教學課程中使用的設定變數：
    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}

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

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

    所需權限

    如要取得完成本快速入門所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

    如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

    您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

  16. 記下 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 角色，遵循最低權限原則。

  17. 將專案的工作流程叫用者角色 (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
  18. 如果您是在 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 要求觸發工作流程時，系統就會執行該工作流程。

  1. 開啟終端機或 Cloud Shell。
  2. 在主目錄中，建立名為 myFirstWorkflow.yaml 或 myFirstWorkflow.json 的新檔案。
  3. 複製以下內容並貼到新檔案中，然後儲存檔案：

    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}"
        }
      }
    ]
  }
}
  4. 部署工作流程： 
    export MY_WORKFLOW=myFirstWorkflow
gcloud workflows deploy ${MY_WORKFLOW} --source=myFirstWorkflow.yaml
     如果您複製了範例工作流程的 JSON 版本，請將 .yaml 替換為 .json。

建立 Eventarc 觸發條件

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

  1. 建立觸發條件，監聽 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 的觸發條件。

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

  2. 確認觸發條件是否已成功建立： 
    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。

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

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

  2. 如要觸發工作流程，請將訊息傳送至 Pub/Sub 主題：

    gcloud pubsub topics publish $TOPIC_ID --message "Hello there"

    產生的事件會以執行階段引數的形式傳遞至工作流程，並傳回「Hello there」訊息。

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

    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，以便在下一個步驟中使用。

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

    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

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

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

清除所用資源

  1. 刪除您建立的工作流程： 
    gcloud workflows delete ${MY_WORKFLOW}
     系統詢問是否要繼續時，請輸入 y。
  2. 刪除您建立的觸發條件： 
    gcloud eventarc triggers delete events-pubsub-trigger
  3. 您也可以刪除專案，以免產生費用。 Google Cloud 刪除 Google Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。

    Delete a Google Cloud project:

    gcloud projects delete PROJECT_ID

後續步驟