使用 Eventarc 接收 Cloud Storage 事件

---

本教學課程說明如何使用經過驗證的 Cloud Run 服務，透過 Eventarc 接收事件，並部署容器化應用程式。

注意：根據預設，所有 Cloud Run 服務都會以私密方式部署，也就是說，如果要求中未提供驗證憑證，就無法存取這些服務。如果專案設有 網域限定共用組織政策，請使用經過驗證的 Cloud Run 目標服務，而非允許公開 (未經驗證) 存取的服務。

為 Eventarc 觸發條件指定篩選器，即可設定事件的轉送方式，包括事件來源和事件目標。在本例中，Cloud Storage 值區的更新會觸發事件，並以 HTTP 要求的形式將要求傳送至 Cloud Run 服務。

目標

在這個教學課程中，您將執行下列操作：

1. 建立 Cloud Storage bucket 做為事件來源。

2. 將事件接收器服務部署至 Cloud Run，該服務需要經過驗證的叫用。

3. 建立 Eventarc 觸發條件，將 Cloud Storage bucket 中的事件轉送至 Cloud Run 服務。

4. 將檔案上傳至 Cloud Storage 值區以產生事件，以及在 Cloud Run 記錄檔中查看該事件。

費用

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

• Artifact Registry
• Cloud Build
• Cloud Run
• Cloud Storage
• Eventarc

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

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

事前準備

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

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.

Install the Google Cloud CLI.

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

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

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Verify that billing is enabled for your Google Cloud project.

Install the Google Cloud CLI.

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

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

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the 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.

Verify that billing is enabled for your Google Cloud project.

1. 如果您並未使用 Cloud Shell，請更新 Google Cloud CLI 元件，並使用您的帳戶登入：

   gcloud components update
   gcloud auth login

2. 啟用 API：

   gcloud services enable artifactregistry.googleapis.com \
       cloudbuild.googleapis.com \
       eventarc.googleapis.com \
       run.googleapis.com \
       storage.googleapis.com

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

   export REGION=us-central1
   gcloud config set run/region ${REGION}
   gcloud config set run/platform managed
   gcloud config set eventarc/location ${REGION}

4. 您或管理員必須為部署者帳戶、觸發程序身分，以及 (選用) Pub/Sub 服務代理程式授予下列 IAM 角色。

   部署者帳戶的必要角色

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

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

      如要取得完成本教學課程所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

      • Cloud Build 編輯器 (roles/cloudbuild.builds.editor)
      • Cloud Run Admin (roles/run.admin)
      • Cloud Run Source Developer (roles/run.sourceDeveloper)
      • Eventarc 管理員 (roles/eventarc.admin)
      • 記錄檔檢視存取者 (roles/logging.viewAccessor)
      • 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
      • 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
      • 服務帳戶使用者 (roles/iam.serviceAccountUser)
      • 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
      • 儲存空間管理員 (roles/storage.admin)

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

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

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

   觸發身分所需的角色

   1. 記下 Compute Engine 預設服務帳戶，因為您會將其附加至 Eventarc 觸發程序，代表觸發程序的身分，以利進行測試。啟用或使用採用 Compute Engine 的服務後，系統會自動建立這個服務帳戶，電子郵件地址格式如下： Google Cloud

      [e-mail]

      將 PROJECT_NUMBER 替換為專案編號。 Google Cloud您可以在 Google Cloud 控制台的「歡迎」頁面找到專案編號，也可以執行下列指令：

      gcloud projects describe PROJECT_ID --format='value(projectNumber)'

      在正式環境中，我們強烈建議建立新的服務帳戶，並授予一或多個包含最低必要權限的 IAM 角色，遵循最低權限原則。

      注意：

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

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

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

   2. 根據預設，只有專案擁有者、專案編輯者，以及 Cloud Run 管理員和叫用者可以呼叫 Cloud Run 服務。您可以依據服務控管存取權，但為了進行測試，請在 Google Cloud 專案中將 Cloud Run 叫用者角色 (run.invoker) 授予 Compute Engine 服務帳戶。這會將角色授予專案中的所有 Cloud Run 服務和工作。

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member=serviceAccount:[e-mail] \
          --role=roles/run.invoker

      請注意，如果您為經過驗證的 Cloud Run 服務建立觸發條件，但未授予 Cloud Run Invoker 角色，系統仍會成功建立並啟用觸發條件。不過，觸發條件不會正常運作，記錄中會顯示類似以下的訊息：

      The request was not authenticated. Either allow unauthenticated invocations or set the proper Authorization header.
   3. 將專案的 Eventarc 事件接收者角色 (roles/eventarc.eventReceiver) 授予 Compute Engine 預設服務帳戶，讓 Eventarc 觸發條件可以接收事件供應商的事件。

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member=serviceAccount:[e-mail] \
          --role=roles/eventarc.eventReceiver

   Pub/Sub 服務代理人的選用角色

   • 如果您是在 2021 年 4 月 8 日當天或之前啟用 Cloud Pub/Sub 服務代理，請將服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予服務代理，以支援已驗證的 Pub/Sub 推送要求。否則，系統會預設授予這個角色：

     gcloud projects add-iam-policy-binding PROJECT_ID \
         --member=serviceAccount:[e-mail] \
         --role=roles/iam.serviceAccountTokenCreator

建立 Artifact Registry 標準存放區

建立 Artifact Registry 標準存放區，用於儲存容器映像檔：

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

將 REPOSITORY 替換成存放區的專屬名稱。

建立 Cloud Storage 值區

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

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

注意： Cloud Storage 值區必須與 Eventarc 觸發程序位於相同Google Cloud 專案和區域或多區域。

建立事件來源後，即可在 Cloud Run 上部署事件接收器服務。

將事件接收器部署至 Cloud Run

部署 Cloud Run 服務，接收及記錄事件。

1. 複製 GitHub 存放區：

   Node.js

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git

   您也可以 下載 zip 格式的範例，然後解壓縮該檔案。

   Python

   git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

   您也可以 下載 zip 格式的範例，然後解壓縮該檔案。

   Go

   git clone https://github.com/GoogleCloudPlatform/golang-samples.git

   您也可以 下載 zip 格式的範例，然後解壓縮該檔案。

   Java

   git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

   您也可以 下載 zip 格式的範例，然後解壓縮該檔案。

   C#

   git clone https://github.com/GoogleCloudPlatform/dotnet-docs-samples.git

   您也可以 下載 zip 格式的範例，然後解壓縮該檔案。

2. 變更為包含 Cloud Run 範例程式碼的目錄：

   Node.js

   cd nodejs-docs-samples/eventarc/audit-storage/

   Python

   cd python-docs-samples/eventarc/audit-storage/

   Go

   cd golang-samples/eventarc/audit_storage/

   Java

   cd java-docs-samples/eventarc/audit-storage/

   C#

   cd dotnet-docs-samples/eventarc/audit-storage/

3. 為 Cloud Run 服務建構容器：

   export PROJECT_ID=$(gcloud config get-value project)
   export SERVICE_NAME=helloworld-events
   gcloud builds submit --tag $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1

4. 將容器映像檔部署至 Cloud Run：

   gcloud run deploy ${SERVICE_NAME} \
       --image $REGION-docker.pkg.dev/${PROJECT_ID}/REPOSITORY/${SERVICE_NAME}:v1

5. 在「Allow unauthenticated invocations to helloworld-events (y/N)?」(允許未經驗證的叫用 helloworld-events 嗎？(y/N)) 提示中，輸入 n 代表「否」。

注意： 根據 Cloud Run 服務所需的網路存取層級，您也可以設定輸入旗標。

看到 Cloud Run 服務網址時，表示部署完成。

建立 Eventarc 觸發條件

Eventarc 觸發條件會將 Cloud Storage bucket 中的事件傳送至 helloworld-events Cloud Run 服務。這項服務需要驗證，且事件應由具備服務帳戶的呼叫端觸發，該帳戶必須擁有使用資源所需的 IAM 角色和權限。

1. 建立用來篩選 Cloud Storage 事件的觸發條件：

   gcloud eventarc triggers create ${SERVICE_NAME} \
       --destination-run-service=${SERVICE_NAME} \
       --destination-run-region=${REGION} \
       --location=${REGION} \
       --event-filters="type=google.cloud.storage.object.v1.finalized" \
       --event-filters="bucket=PROJECT_ID-bucket" \
       --service-account=[e-mail]

   這項操作會建立名為 helloworld-events 的觸發條件。

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

2. 確認觸發條件是否已成功建立。請注意，雖然觸發條件會立即建立，但最多可能需要兩分鐘才能正常運作。

   gcloud eventarc triggers list --location=${REGION}

   畫面會顯示如下的輸出內容：

   NAME: helloworld-events
   TYPE: google.cloud.storage.object.v1.finalized
   DESTINATION: Cloud Run service: helloworld-events
   ACTIVE: Yes
   

產生及查看活動

將文字檔案上傳至 Cloud Storage 值區，產生會轉送至 Cloud Run 服務的事件。Cloud Run 服務會在服務記錄中記錄事件。

1. 如要產生事件，請按照下列步驟操作：

   將文字檔案上傳到 Cloud Storage：

    echo "Hello World" > random.txt
    gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
   

   上傳作業會產生事件，而 Cloud Run 服務會記錄事件的訊息。

2. 如要查看記錄項目：

   1. 篩選記錄檔項目，並以 JSON 格式傳回輸出內容：

      gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
      

   2. 尋找類似下列內容的記錄項目：

      "textPayload": "Detected change in Cloud Storage bucket: objects/random.txt"
      

      注意： 如果沒有看到記錄項目，請稍候幾分鐘，然後重試 gcloud logging read 指令。觸發條件建立完成後，最多可能需要兩分鐘才會開始篩選事件。

記錄需要一些時間才會出現。如果沒有立即看到記錄，請稍候片刻再查看一次。

成功： 您已部署容器化應用程式，並使用經過驗證的 Cloud Run 服務透過 Eventarc 接收事件。

清除所用資源

如果您是為了這個教學課程建立新專案，請刪除專案。如果您使用現有專案，並想保留專案，但不要本教學課程新增的變更，請刪除為本教學課程建立的資源。

刪除專案

如要避免付費，最簡單的方法就是刪除您為了本教學課程所建立的專案。

如要刪除專案：

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。 如果您使用現有專案來進行本文中的工作，刪除專案將一併刪除其中已完成的所有工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

刪除教學課程資源

1. 刪除您在本教學課程中部署的 Cloud Run 服務：

   gcloud run services delete SERVICE_NAME

   其中 SERVICE_NAME 是您選擇的服務名稱。

   您也可以從Google Cloud 控制台刪除 Cloud Run 服務。

2. 移除您在教學課程設定期間新增的任何 gcloud CLI 預設設定。

   例如：

   gcloud config unset run/region

   或

   gcloud config unset project

3. 刪除在本教學課程中建立的其他 Google Cloud 資源：

   • 刪除 Eventarc 觸發條件：

     gcloud eventarc triggers delete TRIGGER_NAME
     

     將 TRIGGER_NAME 替換為觸發條件的名稱。
   • 刪除容器映像檔

後續步驟

• 為其他事件類型建立 Eventarc 觸發條件
• 建構容器
• 開發 Cloud Run 服務