透過 Pub/Sub 事件建立觸發條件

您可以設定 Pub/Sub 觸發條件，叫用 Cloud Run 服務和函式。

設定觸發條件時，您會將觸發條件連結至特定 Pub/Sub 主題。這樣一來，只要有訊息發布至該主題，系統就會自動呼叫您的服務或函式。

您可以透過兩種方式設定這項觸發條件：

  • 直接 Pub/Sub 觸發條件 (建議)：使用 Pub/Sub 將訊息直接轉送至服務或函式。您可直接管理訂閱項目，而服務或函式會收到標準 Pub/Sub 推送要求。如需簡化設定並縮短延遲時間，請使用這個選項。
  • Eventarc 觸發條件：使用 Eventarc 將 Pub/Sub 訊息轉送至服務或函式。Pub/Sub 觸發條件的管理方式與其他 Eventarc 來源相同，服務或函式會以 CloudEvents 的形式接收事件。如需 Eventarc 的進階篩選或轉送功能，請使用這個選項。

事前準備

  1. 請務必按照設定頁面所述，為 Cloud Run 設定新專案。

  2. 啟用 Artifact Registry、Cloud Build、Cloud Run Admin API、Cloud Logging 和 Pub/Sub API：

    啟用 API

    如要設定 Eventarc 觸發條件，也必須啟用 Eventarc API：

    啟用 Eventarc API

必要的角色

授予必要的 IAM 角色和權限。 如要設定以 Eventarc 為基礎的觸發條件，請參閱「Eventarc 必要的 IAM 角色和權限」。

部署者帳戶的必要角色

如要取得透過 Pub/Sub 事件觸發所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

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

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

請注意，根據預設，Cloud Build 權限包含上傳及下載 Artifact Registry 構件的權限。

建立 Pub/Sub 觸發條件

控制台

  1. 在 Google Cloud 控制台中，前往 Cloud Run 的「Services」(服務) 頁面：

    前往 Cloud Run。

  2. 按一下要建立 Pub/Sub 觸發條件的服務或函式。

  3. 選取「觸發條件」分頁標籤。

    選取所選觸發條件設定的分頁標籤：

    1. 按一下 「Add trigger」(新增觸發條件)，然後依序選取「Pub/Sub trigger」(Pub/Sub 觸發條件) >「Direct」(直接)。
    2. 在「Direct Pub/Sub subscription」(直接 Pub/Sub 訂閱項目) 面板中：
      • 在「Cloud Pub/Sub topic」(Cloud Pub/Sub 主題) 欄位中，選取您已建立的主題，或按一下「Create new topic」(建立新主題) 建立新主題。
      • 在「Service account」(服務帳戶) 欄位中，選取訂閱項目用來叫用服務的服務帳戶。如果控制台列出缺少的角色，請按一下「Grant all」(全部授予)。
      • 在「Service URL path」(服務網址路徑) 中，輸入應接收訊息的服務路徑，例如 / (預設) 或 /pubsub。控制台會將這個路徑新增至服務網址。
    3. 按一下「儲存」。

    Eventarc

    在「Eventarc trigger」(Eventarc 觸發條件) 窗格中，按照下列步驟修改觸發條件詳細資料：

    1. 在「Trigger name」(觸發條件名稱) 欄位中輸入觸發條件名稱，或使用預設名稱。

    2. 從清單中選取「觸發條件類型」：

      • Google 來源：指定 Pub/Sub、Cloud Storage、Firestore 和其他 Google 事件提供者的觸發條件。

      • 第三方：與提供 Eventarc 來源的非 Google 供應商整合。詳情請參閱「Eventarc 中的第三方事件」。

    3. 從「Event provider」(事件供應商) 清單中選取「Pub/Sub」，選取提供觸發函式事件類型的產品。如需事件提供者清單，請參閱「事件提供者和目的地」。

    4. 從「Event type」(事件類型) 清單中選取「google.cloud.pubsub.topic.v1.messagePublished」。觸發條件設定會因支援的事件類型而異。詳情請參閱「事件類型」。

    5. 從「Select a Cloud Pub/Sub topic」(選取 Cloud Pub/Sub 主題) 清單中，選取觸發條件要監控的主題。發布至這個主題的訊息會觸發函式呼叫。

    6. 如果「Region」(區域) 欄位已啟用，請選取 Eventarc 觸發條件的位置。一般來說，Eventarc 觸發條件的位置應與要監控事件的Google Cloud 資源位置相符。在多數情況下，您也應在相同區域部署函式。如要進一步瞭解 Eventarc 觸發條件位置，請參閱「瞭解 Eventarc 位置」。

    7. 在「Service account」(服務帳戶) 欄位中，選取服務帳戶。Eventarc 觸發條件會連結至服務帳戶，在叫用函式時做為身分識別。Eventarc 觸發條件的服務帳戶必須具備叫用函式的權限。根據預設，Cloud Run 會使用 Compute Engine 預設服務帳戶。

    8. 您可以視需要指定服務網址路徑，將傳入的要求傳送至該路徑。這是目的地服務上的相對路徑，觸發條件的事件應傳送至該路徑。例如：/、/route、route 和 route/subroute。

    9. 如要在傳送失敗時啟用重試功能，請勾選「Enable retry on failure」(啟用失敗時重試) 核取方塊。如未勾選，預設行為是只傳送一次，不重試。詳情請參閱「重試事件」。

    10. 填妥必填欄位後，按一下「儲存觸發條件」。

gcloud

如要使用 gcloud CLI 為服務或函式建立觸發條件，請按照下列步驟操作：

  1. 如果尚未部署服務或函式，請先完成這項操作。

  2. 如果您已有 Pub/Sub 主題，請略過這個步驟。否則，請建立 Pub/Sub 主題：

    gcloud pubsub topics create TOPIC_NAME

  3. 選取所選觸發條件設定的分頁標籤：

    直接

    1. 為 Pub/Sub 服務代理設定必要角色：

      Pub/Sub 服務代理的必要角色

      下列步驟說明如何建立及使用服務帳戶，讓 Pub/Sub 訂閱項目能使用該帳戶叫用服務或函式。使用 Google Cloud CLI 建立 Pub/Sub 觸發條件指令時，必須執行這些步驟。如果您使用 Google Cloud 控制台建立觸發條件，可以略過這些步驟。

      1. 建立或選取服務帳戶，代表 Pub/Sub 訂閱項目身分。

             gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
        --display-name "Cloud Run Pub/Sub Invoker"

        將 SERVICE_ACCOUNT_NAME 替換為服務帳戶的專屬名稱。

      2. 為叫用者服務帳戶授予叫用服務的權限：

          gcloud run services add-iam-policy-binding SERVICE_NAME \
     --member=serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID. \
     --role=roles/run.invoker

        IAM 變更可能需要幾分鐘才會生效。在此期間，您可能會在服務記錄中看到 HTTP 403 錯誤。

      3. 允許 Pub/Sub 在專案中建立驗證權杖：

          gcloud projects add-iam-policy-binding PROJECT_ID \
     --member=serviceAccount:service-PROJECT_NUMBER@gcp-sa-pubsub. \
     --role=roles/iam.serviceAccountTokenCreator

        更改下列內容：

        • PROJECT_ID：您的 Google Cloud 專案 ID。
        • PROJECT_NUMBER：您的 Google Cloud 專案編號。

        專案 ID 和專案編號會列在Google Cloud 控制台的「Project info」(專案資訊) 面板中。

    2. 使用服務帳戶建立 Pub/Sub 訂閱項目：

      gcloud pubsub subscriptions create SUBSCRIPTION_NAME \
  --topic TOPIC_NAME \
  --ack-deadline=600 \
  --push-endpoint=SERVICE_URL/ \
  --push-auth-service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

      更改下列內容：

      • SUBSCRIPTION_NAME：要建立的訂閱項目名稱。
      • TOPIC_NAME：先前建立的主題名稱。
      • SERVICE_URL：部署服務時提供的 HTTPS 網址。即使您已新增網域對應，這個網址仍可正常運作。
      • SERVICE_ACCOUNT_NAME：先前建立的服務帳戶名稱。
      • PROJECT_ID：您的 Google Cloud 專案 ID。

      注意：

      • --push-auth-service-account 旗標會啟用 Pub/Sub 推送功能，用於驗證與授權。

      • 系統會自動註冊 Cloud Run 服務網域，以便與 Pub/Sub 訂閱項目搭配使用。

      • 僅限 Cloud Run：內建驗證機制會檢查權杖是否有效，授權機制則會檢查服務帳戶是否有權叫用 Cloud Run 服務。

    Eventarc

    執行下列指令，建立篩選及轉送事件的觸發條件：

    gcloud eventarc triggers create TRIGGER_NAME  \
   --location=LOCATION \
   --destination-run-service=DESTINATION_RUN_SERVICE  \
   --destination-run-region=DESTINATION_RUN_REGION \
   --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" \
   --transport-topic=projects/PROJECT_ID/topics/TOPIC_NAME \
   --service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.

    更改下列內容：

    • TRIGGER_NAME：觸發條件 ID 或完整 ID。
    • LOCATION：Eventarc 觸發條件的位置。或者，您也可以設定 eventarc/location 屬性，例如 gcloud config set eventarc/location us-central1。

      為避免效能和資料落地問題，位置必須與產生事件的 Google Cloud 服務位置相符。詳情請參閱「Eventarc 位置」。

    • DESTINATION_RUN_SERVICE：已部署服務或 Cloud Run 函式的名稱，用於接收觸發條件的事件。
    • DESTINATION_RUN_REGION：(選用) 目的地 Cloud Run 函式所在的Cloud Run location。如未指定，系統會假設函式與觸發條件位於相同區域。
    • --event-filters="type=google.cloud.pubsub.topic.v1.messagePublished" 旗標為必要，且無法變更。如要使用其他事件類型，則必須建立新的觸發條件。
    • TOPIC_NAME：現有 Pub/Sub 主題的 ID。主題必須與觸發條件位於相同專案。
    • SERVICE_ACCOUNT_NAME：使用者自行管理的服務帳戶名稱。
    • PROJECT_ID：您的 Google Cloud 專案 ID。

    注意：

    • 如要指定單一事件傳送嘗試，不進行重試，請使用 --max-retry-attempts 旗標。唯一有效的值是 1。如果省略這個旗標，系統會套用標準重試行為。詳情請參閱「重試事件」。
    • 您也可以使用其他旗標。詳情請參閱「gcloud eventarc triggers create」。

Terraform

如要為 Cloud Run 函式建立 Eventarc 觸發條件，請參閱「使用 Terraform 建立觸發條件」。

後續步驟