接收 Cloud Storage 的直接事件 (gcloud CLI)

本快速入門導覽課程說明如何使用 Eventarc，在未經驗證的 Cloud Run 服務中，接收 Cloud Storage 的直接事件 (不使用 Cloud 稽核記錄)。

您可以設定在 Cloud Storage 值區內發生各種事件時觸發通知，包括建立、刪除、封存物件，以及更新中繼資料。詳情請參閱「建立觸發條件，將 Cloud Storage 事件轉送至 Cloud Run」。

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

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

  2. 將事件接收器服務部署至 Cloud Run。

  3. 建立 Eventarc 觸發條件。

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

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 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. 啟用 Cloud Run、Cloud Storage、Eventarc 和 Pub/Sub API。

    gcloud services enable \
eventarc.googleapis.com \
pubsub.googleapis.com \
run.googleapis.com \
storage.googleapis.com
  13. 更新 gcloud 元件： 
    gcloud components update
  14. 登入帳戶： 
    gcloud auth login
  15. 設定本快速入門導覽課程中使用的設定變數： 
    gcloud config set run/region us-central1
gcloud config set run/platform managed
gcloud config set eventarc/location us-central1

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

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

    所需權限

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

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

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

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

  18. 將專案的 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
  19. 建立 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'
  20. 如果您是在 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 Run 上部署事件接收器服務。

將事件接收器服務部署至 Cloud Run

使用預先建構的映像檔 us-docker.pkg.dev/cloudrun/container/hello，部署 Cloud Run 服務來接收及記錄事件：

gcloud run deploy helloworld-events \
    --image=us-docker.pkg.dev/cloudrun/container/hello \
    --allow-unauthenticated

部署成功後，指令列會顯示服務網址。

您已將名為 helloworld-events 的事件接收器服務部署至 Cloud Run，現在可以設定觸發條件。

建立 Eventarc 觸發條件

Eventarc 觸發條件會將 Cloud Storage bucket 中的事件傳送至 helloworld-events Cloud Run 服務。

  1. 建立用來篩選 Cloud Storage 事件的觸發條件，並使用 Compute Engine 預設服務帳戶。

      gcloud eventarc triggers create storage-events-trigger \
      --destination-run-service=helloworld-events \
      --destination-run-region=us-central1 \
      --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 服務代理程式的佈建作業可能會延遲。這個問題通常可以透過再次建立觸發條件來解決。詳情請參閱「權限遭拒錯誤」。

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

      gcloud eventarc triggers list --location=us-central1

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

     NAME                    TYPE                                      DESTINATION_RUN_SERVICE  DESTINATION_RUN_PATH  ACTIVE
 storage-events-trigger  google.cloud.storage.object.v1.finalized  helloworld-events                              Yes

產生及查看活動

  1. 如要產生事件，請將文字檔案上傳到 Cloud Storage：

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

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

  2. 如要查看記錄項目，請篩選記錄項目，然後以 JSON 格式傳回輸出內容：

    gcloud logging read 'jsonPayload.message: "Received event of type google.cloud.storage.object.v1.finalized."'

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

    jsonPayload:
  event:
  ...
  eventType: google.cloud.storage.object.v1.finalized
  message: |
    Received event of type google.cloud.storage.object.v1.finalized. Event data: {
      "kind": "storage#object",
      "id": "PROJECT_ID-bucket/random.txt/1713970683868432",
      "selfLink": "https://www.googleapis.com/storage/v1/b/PROJECT_ID-bucket/o/random.txt",
      "name": "random.txt",
      "bucket": "PROJECT_ID-bucket",
      ...
    }

恭喜！您已成功將事件接收器服務部署至 Cloud Run、建立 Eventarc 觸發程序、從 Cloud Storage 產生事件，並在 Cloud Run 記錄檔中查看該事件。

清除所用資源

完成本文所述工作後，您可以刪除已建立的資源，避免繼續計費。

您可以：

  1. 刪除 Cloud Storage 值區。

  2. 刪除 Cloud Run 服務。

  3. 刪除 Eventarc 觸發條件。

或者，您也可以刪除 Google Cloud 專案，以免產生費用。 刪除 Google Cloud 專案後，系統就會停止對專案使用的所有資源收取費用。

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

如果打算進行多個教學課程及快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

後續步驟