本教學課程說明如何使用 Google Cloud CLI,在 Cloud Run 中部署事件驅動函式,並使用 Eventarc 觸發函式來回應 Cloud Storage 事件。
為 Eventarc 觸發條件指定篩選器,即可設定事件的轉送方式,包括事件來源和事件目標。以本教學課程的範例來說,Cloud Storage bucket 的更新會觸發事件,並以 HTTP 要求的形式將要求傳送至函式。
目標
在這個教學課程中,您將執行下列操作:
費用
在本文件中,您會使用 Google Cloud的下列計費元件:
如要根據預測用量估算費用,請使用 Pricing Calculator。
事前準備
貴機構定義的安全性限制,可能會導致您無法完成下列步驟。如需疑難排解資訊,請參閱「在受限的 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.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
-
-
Make sure that billing is enabled for your Google Cloud project.
-
Install the Google Cloud CLI.
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
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.
-
-
Make sure that billing is enabled for your Google Cloud project.
- 如果您並未使用 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}
設定必要角色
您或管理員必須授予部署者帳戶、觸發程序身分,以及視需要授予 Pub/Sub 服務代理程式和 Cloud Storage 服務代理程式下列 IAM 角色。
部署者帳戶的必要角色
-
如果您是專案建立者,系統會授予基本「擁有者」角色 (
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 編輯器 (
觸發身分所需的角色
記下 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)'
- 根據預設,只有專案擁有者、專案編輯者,以及 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 Invoker 角色,系統仍會成功建立並啟用觸發條件。不過,觸發條件不會正常運作,記錄中會顯示類似以下的訊息:
The request was not authenticated. Either allow unauthenticated invocations 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 值區
建立要用做事件來源的 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 依附元件:在
helloGCS
目錄中建立index.js
檔案,並加入下列 Node.js 範例:
Python
建立一個新目錄並命名為
helloGCS
,然後將目錄變更為該目錄:mkdir helloGCS cd helloGCS
在
helloGCS
目錄中建立requirements.txt
檔案,指定 Python 依附元件:這會新增範例所需的套件。
在
helloGCS
目錄中建立main.py
檔案,並加入下列 Python 範例:
部署事件導向函式
在包含範例程式碼的目錄中,執行下列指令來部署名為 helloworld-events
的函式:
Node.js
gcloud run deploy helloworld-events \
--source . \
--function helloGCS \
--base-image BASE_IMAGE \
--region us-central1
將 BASE_IMAGE 替換為函式的基礎映像檔環境,例如 nodejs22
。如要進一步瞭解基礎映像檔和每個映像檔中包含的套件,請參閱「支援的語言執行階段和基礎映像檔」。
Python
gcloud run deploy helloworld-events \
--source . \
--function hello_gcs \
--base-image BASE_IMAGE \
--region us-central1
將 BASE_IMAGE 替換為函式的基礎映像檔環境,例如 python313
。如要進一步瞭解基礎映像檔和每個映像檔中包含的套件,請參閱「支援的語言執行階段和基礎映像檔」。
部署完成後,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 改成您的專案 ID。 Google Cloud
- 將 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 函式會記錄事件的訊息。
如要查看記錄項目:
篩選記錄檔項目,並以 JSON 格式傳回輸出內容:
gcloud logging read "resource.labels.service_name=helloworld-events AND textPayload:random.txt" --format=json
尋找類似下列內容的記錄項目:
[ { .... "resource": { "labels": { .... "location": "us-central1", ..... "service_name": "helloworld-events" }, }, "textPayload": "File: random.txt", ..... } ]
記錄需要一些時間才會出現。如果沒有立即看到記錄,請稍候片刻再查看一次。
看到記錄檔項目後,表示您已成功部署事件驅動函式,且該函式會在文字檔上傳至 Cloud Storage 時觸發。
清除所用資源
如果您是為了這個教學課程建立新專案,請刪除專案。如果您使用現有專案,並想保留專案,但不要本教學課程新增的變更,請刪除為本教學課程建立的資源。
刪除專案
如要避免付費,最簡單的方法就是刪除您為了本教學課程所建立的專案。
如要刪除專案:
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
刪除教學課程資源
刪除您在本教學課程中部署的 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 觸發條件: