Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

使用 Eventarc 從 Cloud Storage 觸發函式

本教學課程說明如何使用 Google Cloud CLI，在 Cloud Run 部署事件導向函式，並透過 Eventarc 觸發函式，回應 Cloud Storage 事件。

為 Eventarc 觸發條件指定篩選器，即可設定事件轉送，包括事件來源和事件目標。在本教學課程的範例中，Cloud Storage bucket 的更新會觸發事件，並以 HTTP 要求的形式傳送要求至函式。

目標

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

建立 Cloud Storage bucket 做為事件來源。
部署事件導向函式。
建立 Eventarc 觸發條件。
將檔案上傳至 Cloud Storage，觸發函式。

費用

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

您可以使用 Pricing Calculator，根據預測用量估算費用。

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

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 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 專案已啟用計費功能。

如果您不是使用 Cloud Shell，請更新 Google Cloud CLI 元件，並使用帳戶登入：
```
gcloud components update
gcloud auth login
```

啟用 API：

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

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

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

如果專案受限於限制未經驗證叫用的網域限制組織政策，您必須按照「測試私人服務」一節所述的方式存取已部署的服務。

設定必要角色

您或管理員必須將下列 IAM 角色授予部署者帳戶、觸發條件身分，以及 Pub/Sub 服務代理和 Cloud Storage 服務代理 (選用)。

部署者帳戶的必要角色

如果您是專案建立者，系統會授予您基本擁有者角色 (roles/owner)。根據預設，這個 Identity and Access Management (IAM) 角色包含完整存取大多數 Google Cloud資源所需的權限，您可以略過這個步驟。

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

如要取得完成本教學課程所需的權限，請要求管理員在專案中授予您下列 IAM 角色：
- Cloud Run 原始碼開發人員 (roles/run.sourceDeveloper)
- 記錄檔檢視存取者 (roles/logging.viewAccessor)
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
- 服務帳戶使用者 (roles/iam.serviceAccountUser)
- 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

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

觸發條件身分的必要角色

記下 Compute Engine 預設服務帳戶，因為您會將其附加至 Eventarc 觸發條件，代表觸發條件的身分，以便進行測試。啟用或使用採用 Compute Engine 的 Google Cloud 服務後，系統會自動建立這個服務帳戶，電子郵件格式如下：
```
PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
將 PROJECT_NUMBER 替換為您的 Google Cloud專案編號。您可以在 Google Cloud 控制台的「Welcome」(歡迎) 頁面找到專案編號，也可以執行下列指令：
```
gcloud projects describe PROJECT_ID --format='value(projectNumber)'
```
在正式環境中，強烈建議您建立新的服務帳戶，並授予一或多個 IAM 角色，其中包含所需最低權限，並遵循最小權限原則。

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

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

如果預設服務帳戶已具備「編輯者」角色，建議您將「編輯者」角色替換為權限較少的角色。如要安全修改服務帳戶的角色，請使用 Policy Simulator 查看變更會造成的影響，然後授予及撤銷適當的角色。
根據預設，只有專案擁有者、專案編輯者、Cloud Run 管理員和叫用者可以呼叫 Cloud Run 服務。您可以依據服務控管存取權，但為了測試，請將 Google Cloud 專案的 Cloud Run 叫用者角色 (run.invoker) 授予 Compute Engine 服務帳戶。這會授予專案中所有 Cloud Run 服務和工作的角色。
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/run.invoker
```
請注意，如果您為已驗證的 Cloud Run 服務建立觸發條件，但未授予 Cloud Run 叫用者角色，觸發條件會成功建立並啟用。不過，觸發條件不會如預期運作，且記錄中會顯示類似下列的訊息：
The request was not authenticated. Either allow public access or set the proper Authorization header.

將專案的 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

Cloud Storage 服務代理的選用角色

為 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'

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

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

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

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

編寫事件導向函式

如要編寫事件導向函式，請按照下列步驟操作：

Node.js

建立一個新目錄並命名為 helloGCS，然後將目錄變更為該目錄：
```
   mkdir helloGCS
   cd helloGCS
```

在 helloGCS 目錄中建立 package.json 檔案，指定 Node.js 依附元件：

{
  "name": "nodejs-docs-samples-functions-v2-storage",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google LLC",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=20.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=60000"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^5.0.0"
  },
  "devDependencies": {
    "c8": "^12.0.0",
    "mocha": "^10.0.0",
    "sinon": "^18.0.0",
    "supertest": "^7.0.0"
  }
}

在 helloGCS 目錄中建立 index.js 檔案，並加入以下 Node.js 範例：

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent callback with the Functions Framework that will
// be triggered by Cloud Storage.
functions.cloudEvent('helloGCS', cloudEvent => {
  console.log(`Event ID: ${cloudEvent.id}`);
  console.log(`Event Type: ${cloudEvent.type}`);

  const file = cloudEvent.data;
  console.log(`Bucket: ${file.bucket}`);
  console.log(`File: ${file.name}`);
  console.log(`Metageneration: ${file.metageneration}`);
  console.log(`Created: ${file.timeCreated}`);
  console.log(`Updated: ${file.updated}`);
});

Python

建立一個新目錄並命名為 helloGCS，然後將目錄變更為該目錄：
```
   mkdir helloGCS
   cd helloGCS
```
在 helloGCS 目錄中建立 requirements.txt 檔案，指定 Python 依附元件：
```
functions-framework==3.9.2
cloudevents==1.11.0
```
這會新增範例所需的套件。

在 helloGCS 目錄中建立 main.py 檔案，並加入以下 Python 範例：

from cloudevents.http import CloudEvent

import functions_framework


# Triggered by a change in a storage bucket
@functions_framework.cloud_event
def hello_gcs(cloud_event: CloudEvent) -> tuple:
    """This function is triggered by a change in a storage bucket.

    Args:
        cloud_event: The CloudEvent that triggered this function.
    Returns:
        The event ID, event type, bucket, name, metageneration, and timeCreated.
    """
    data = cloud_event.data

    event_id = cloud_event["id"]
    event_type = cloud_event["type"]

    bucket = data["bucket"]
    name = data["name"]
    metageneration = data["metageneration"]
    timeCreated = data["timeCreated"]
    updated = data["updated"]

    print(f"Event ID: {event_id}")
    print(f"Event type: {event_type}")
    print(f"Bucket: {bucket}")
    print(f"File: {name}")
    print(f"Metageneration: {metageneration}")
    print(f"Created: {timeCreated}")
    print(f"Updated: {updated}")

    return event_id, event_type, bucket, name, metageneration, timeCreated, updated

部署事件導向函式

在包含程式碼範例的目錄中執行下列指令，部署名為 helloworld-events 的函式：

Node.js

gcloud run deploy helloworld-events \
      --source . \
      --function helloGCS \
      --base-image BASE_IMAGE \
      --region us-central1

將 BASE_IMAGE 替換為函式的基本映像檔環境，例如 nodejs24。如要進一步瞭解基礎映像檔和各映像檔包含的套件，請參閱「支援的語言執行階段和基礎映像檔」。

Python

gcloud run deploy helloworld-events \
      --source . \
      --function hello_gcs \
      --base-image BASE_IMAGE \
      --region us-central1

將 BASE_IMAGE 替換為函式的基本映像檔環境，例如 python314。如要進一步瞭解基礎映像檔和各映像檔包含的套件，請參閱「支援的語言執行階段和基礎映像檔」。

部署作業完成後，Google Cloud CLI 會顯示服務執行所在的網址。

建立 Eventarc 觸發條件

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

建立用來篩選 Cloud Storage 事件的觸發條件：
```
gcloud eventarc triggers create TRIGGER_NAME  \
    --location=${REGION} \
    --destination-run-service=helloworld-events  \
    --destination-run-region=${REGION} \
    --event-filters="type=google.cloud.storage.object.v1.finalized" \
    --event-filters="bucket=PROJECT_ID-bucket" \
    --service-account=PROJECT_NUMBER-compute@developer.gserviceaccount.com
```
更改項目：
- 將 TRIGGER_NAME 替換成觸發條件名稱。
- 將 PROJECT_ID 替換為 Google Cloud 專案 ID。
- PROJECT_NUMBER 替換為 Google Cloud 專案編號。
請注意，在 Google Cloud 專案中首次建立 Eventarc 觸發條件時，Eventarc 服務代理的佈建作業可能會延遲。這個問題通常可以透過再次嘗試建立觸發條件來解決。詳情請參閱「權限遭拒錯誤」。

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

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

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

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

產生及查看事件

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

將文字檔案上傳到 Cloud Storage，以便產生事件：
```
 echo "Hello World" > random.txt
 gcloud storage cp random.txt gs://PROJECT_ID-bucket/random.txt
```
上傳作業會產生事件，Cloud Run 函式則會記錄事件訊息。
如要查看記錄項目，請按照下列步驟操作：
1. 篩選記錄項目，並以 JSON 格式傳回輸出內容：
```
gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
```
2. 尋找類似下列內容的記錄項目：
```
[
  {
   ....
    "resource": {
      "labels": {
        ....
        "location": "us-central1",
        .....
        "service_name": "helloworld-events"
      },
    },
    "textPayload": "File: random.txt",
     .....
  }
]
```
  注意： 如果沒有看到記錄項目，請稍候幾分鐘，然後再次執行 gcloud logging read 指令。觸發條件建立後，最多可能需要兩分鐘才會開始篩選事件。
  記錄需要一些時間才會出現。如果沒有立即看到，請稍待一分鐘後再查看。

看到記錄項目後，即代表您已成功部署事件導向函式，並在文字檔案上傳至 Cloud Storage 時觸發。

清除所用資源

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

刪除專案

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

刪除專案的方法如下：

前往 Google Cloud 控制台的「Manage resources」(管理資源) 頁面。
前往「Manage resources」(管理資源)
在專案清單中選取要刪除的專案，然後點選「Delete」(刪除)。
在對話方塊中輸入專案 ID，然後按一下 [Shut down] (關閉) 以刪除專案。

刪除教學課程資源

刪除您在本教學課程中部署的 Cloud Run 服務：
```
gcloud run services delete SERVICE_NAME
```
其中 SERVICE_NAME 是您選擇的服務名稱。

您也可以從Google Cloud 控制台刪除 Cloud Run 服務。
移除您在教學課程設定期間新增的任何 gcloud CLI 預設設定。

例如：

gcloud config unset run/region

或

gcloud config unset project
刪除在本教學課程中建立的其他 Google Cloud 資源：
- 刪除 Eventarc 觸發條件：
```
gcloud eventarc triggers delete TRIGGER_NAME
```
  將 TRIGGER_NAME 替換為觸發條件名稱。

使用 Eventarc 從 Cloud Storage 觸發函式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

目標

費用

事前準備

設定必要角色

部署者帳戶的必要角色

觸發條件身分的必要角色

Cloud Storage 服務代理的選用角色

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

建立 Cloud Storage bucket

編寫事件導向函式

Node.js

Python

部署事件導向函式

Node.js

Python

建立 Eventarc 觸發條件

產生及查看事件

清除所用資源

刪除專案

刪除教學課程資源

後續步驟

使用 Eventarc 從 Cloud Storage 觸發函式