使用 Eventarc 和 Cloud Run 函式觸發 Cloud Storage 的事件處理

1. 總覽

在本實驗室中，您將瞭解如何使用 Cloud Storage bucket 事件和 Eventarc 觸發事件處理作業。您將使用 Cloud Run 函式分析資料及處理圖片。這項函式會使用 Google 的 Vision API，並將處理後的圖片存回 Cloud Storage 值區。

學習目標

如何建構影像處理管道。

設定 Storage bucket
建立 Cloud Run functions，在 Cloud Storage 中讀取及寫入物件
部署 Eventarc 觸發條件
整合 Vision API 來偵測食物圖片
測試並驗證端對端解決方案

必要條件

本實驗室假設您已熟悉 Cloud 控制台和殼層環境。
具備 Cloud Storage、Cloud Run 函式或 Vision API 的相關經驗會有幫助，但並非必要條件。

2. 設定和需求

設定 Cloud 專案

登入 Google Cloud 控制台，然後建立新專案或重複使用現有專案。如果沒有 Gmail 或 Google Workspace 帳戶，請先建立帳戶。

專案名稱是這個專案參與者的顯示名稱。這是 Google API 未使用的字元字串。你隨時可以更新。
專案 ID 在所有 Google Cloud 專案中都是不重複的，而且設定後即無法變更。Cloud 控制台會自動產生專屬字串，通常您不需要在意該字串為何。在大多數程式碼研究室中，您需要參照專案 ID (通常標示為 PROJECT_ID)。如果您不喜歡產生的 ID，可以產生另一個隨機 ID。你也可以嘗試使用自己的名稱，看看是否可用。完成這個步驟後就無法變更，且專案期間會維持不變。
請注意，有些 API 會使用第三個值，也就是「專案編號」。如要進一步瞭解這三種值，請參閱說明文件。

接著，您需要在 Cloud 控制台中啟用帳單，才能使用 Cloud 資源/API。完成這個程式碼研究室的費用不高，甚至可能完全免費。如要關閉資源，避免在本教學課程結束後繼續產生費用，請刪除您建立的資源或專案。Google Cloud 新使用者可參加 $300 美元的免費試用計畫。

啟用 Cloud Shell

按一下搜尋列右側的圖示，啟用 Cloud Shell。

環境設定

在 Cloud Shell 終端機中執行下列指令，建立專案和資源相關的環境變數。

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NAME=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export REGION=us-east1 
export UPLOAD_BUCKET_NAME=menu-item-uploads-$PROJECT_ID
export UPLOAD_BUCKET=gs://menu-item-uploads-$PROJECT_ID
export BUCKET_THUMBNAILS=gs://menu-item-thumbnails-$PROJECT_ID
export MENU_SERVICE_NAME=menu-service
export USER_EMAIL=$(gcloud config list account --format "value(core.account)")

啟用實驗室所需的 API

gcloud services enable \
    vision.googleapis.com \
    cloudfunctions.googleapis.com \
    pubsub.googleapis.com \
    cloudbuild.googleapis.com \
    logging.googleapis.com \
    eventarc.googleapis.com \
    artifactregistry.googleapis.com \
    run.googleapis.com \
    --quiet

複製存放區

git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. 設定 Cloud Storage bucket

建立儲存空間 bucket

為圖片處理管道建立上傳和縮圖 Cloud Storage bucket。

使用 gsutil mb 指令和專屬名稱建立兩個值區：

上傳圖片的 bucket
縮圖 bucket，用於儲存產生的縮圖圖片

建立 bucket 並上傳新圖片：

gsutil mb -p $PROJECT_ID -l $REGION $UPLOAD_BUCKET

輸出內容範例：

Creating gs://menu-item-uploads-cymbal-eats-8399-3119/...

建立用來儲存所產生縮圖的值區：

gsutil mb -p $PROJECT_ID -l $REGION $BUCKET_THUMBNAILS

輸出內容範例：

Creating gs://menu-item-thumbnails-cymbal-eats-8399-3119/...

更新 Bucket 權限

更新儲存空間值區權限，允許使用者讀取。

使用 gsutil iam ch 指令，授予讀取及寫入值區中物件的權限：

gsutil iam ch allUsers:objectViewer $UPLOAD_BUCKET
gsutil iam ch allUsers:objectViewer $BUCKET_THUMBNAILS

輸出範例

Updated IAM policy for project [cymbal-eats-8399-3119].
[...]

4. 設定服務帳戶

建立自訂服務帳戶，供 Cloud Function 處理縮圖：

export CF_SERVICE_ACCOUNT=thumbnail-service-sa
gcloud iam service-accounts create ${CF_SERVICE_ACCOUNT}

授予 artifactregistry.reader 角色，允許從 Artifact Registry 讀取資料：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/artifactregistry.reader"

授予 storage.objectCreator 角色，允許將生成的圖像儲存在縮圖 bucket 中：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/storage.objectCreator"

授予 run.invoker 角色，允許叫用 Cloud Run 服務：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/run.invoker"

授予「eventarc.eventReceiver」角色，允許接收來自供應商的事件：

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member "serviceAccount:${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role "roles/eventarc.eventReceiver"

將 pubsub.publisher 角色授予 Cloud Storage 服務帳戶。這樣一來，服務帳戶就能在圖片上傳至值區時發布事件。

GCS_SERVICE_ACCOUNT=$(gsutil kms serviceaccount -p $PROJECT_NUMBER)

gcloud projects add-iam-policy-binding $PROJECT_NUMBER \
    --member "serviceAccount:$GCS_SERVICE_ACCOUNT" \
    --role "roles/pubsub.publisher"

5. 影像處理函式總覽

建立函式，從 Cloud Storage 下載圖片、調整圖片大小，然後將圖片上傳回 Cloud Storage。函式會呼叫 Vision API，為圖片指派說明標籤。這項函式會檢查說明標籤。如果標籤將圖片識別為「食物」，系統就會將事件傳送至菜單服務，更新菜單項目的圖片和縮圖。

觸發函式

Cloud Storage 函式以 Cloud Storage 的 Pub/Sub 通知為基礎，並且支援類似的事件類型：

在本實驗室中，您會在 Cloud Storage 中完成物件時，部署及觸發函式。

物件建立完成

如果 Cloud Storage 物件順利「寫入」完畢，就會觸發物件完成事件。具體來說，建立新物件或覆寫現有物件都會觸發這個事件。這個觸發程序會忽略封存和中繼資料更新作業。

6. 整合 Cloud Storage

Cloud Storage 是在 Google Cloud 中為您儲存物件的服務。物件是不可變更的資料片段，由任何格式的檔案組成。物件會存放在名為值區的容器中。所有值區都與專案相關聯，您可以在機構底下為專案分組。用戶端程式庫和 API 可讓您輕鬆整合 Cloud Storage

在本實驗室中，您將使用用戶端程式庫，在 Cloud Storage 中讀取及寫入物件。

安裝用戶端程式庫

Cloud 用戶端程式庫支援多種常見程式語言，如要開始使用程式庫，請安裝用戶端程式庫。

使用用戶端程式庫

實作細節大致上取決於程式設計語言。如要在應用程式中使用用戶端程式庫，第一步是匯入 Cloud Storage 依附元件。舉例來說，在 Node.js 專案中，匯入項目會新增至 package.json 檔案。以下程式碼片段顯示本實驗室的 package.json 檔案注意事項。

package.json

{
    "name": "thumbnail-service",
    "version": "0.1.0",
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0",
      "@google-cloud/storage": "^5.18.2",
      "@google-cloud/vision": "^2.4.2",
        ...
    }
  }

註冊 CloudEvent 回呼

向 Functions Framework 註冊 CloudEvent 回呼，當新圖片上傳至 bucket 時，Cloud Storage 會觸發該回呼。

index.js

functions.cloudEvent('process-thumbnails', async (cloudEvent) => {
    console.log(`Event ID: ${cloudEvent.id}`);
    console.log(`Event Type: ${cloudEvent.type}`);
    ...

建立儲存空間參照物件

匯入用戶端程式庫後，您需要建立新的儲存空間用戶端，以及應用程式將互動的 bucket。

index.js

const storage = new Storage();
const bucket = storage.bucket(file.bucket);
const thumbBucket = storage.bucket(process.env.BUCKET_THUMBNAILS);

下載 Cloud Storage 物件

index.js

await bucket.file(file.name).download({
            destination: originalFile
        });

將物件上傳至 Cloud Storage

您可以透過三種方式將上傳要求傳送至 Cloud Storage：單一要求、可續傳或 XML API 多部分上傳。如要上傳較大的檔案或串流上傳，請使用支援續傳的上傳功能。使用 XML API 時，檔案會分部分上傳，然後組合成單一物件。如果是較小的物件，請使用單一要求上傳。

下列程式碼會使用單一要求上傳，將圖片上傳至 Cloud Storage。

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. 整合 Vision API

開發人員可透過 Cloud Vision，輕鬆將視覺偵測功能整合至應用程式，包括為圖片加上標籤、臉部和地標偵測、光學字元辨識 (OCR)，以及為煽情露骨內容加上標記。

安裝用戶端程式庫

Cloud 用戶端程式庫支援多種常見程式語言，如要開始使用程式庫，請安裝用戶端程式庫。

建立圖片註解工具用戶端

如要使用官方用戶端 SDK 存取 Google API，請根據 API 的探索文件建立服務物件，向 SDK 說明 API。您必須使用憑證，從 Vision API 的探索服務擷取這項資訊。

index.js

const client = new vision.ImageAnnotatorClient();

建構 Vision API 要求

您可以將圖片檔案內容以 base64 編碼字串的形式，傳送至要求主體，讓 Vision API 對圖片檔案執行特徵偵測。

如要使用 images 資源建立要求，請為圖片加上註解。對這項 API 發出的要求會以物件形式呈現，並包含要求清單。這份清單中的每個項目都包含兩項資訊：

Base64 編碼的圖片資料
您希望系統為該圖片註解的功能清單。

index.js

        const client = new vision.ImageAnnotatorClient();
        const visionRequest = {
            image: { source: { imageUri: `gs://${file.bucket}/${file.name}` } },
            features: [
                { type: 'LABEL_DETECTION' },
            ]
        };
        const visionPromise = client.annotateImage(visionRequest);

8. 部署 Cloud Run 函式

這項圖片大小調整服務是 Cymbal Eats 系統的一部分。在本節中，您只會部署與圖片處理功能相關的元件。完整安裝作業會納入上傳圖片的 UI，以及儲存產生中繼資料的下游要求。這些功能不會在這個實驗室中安裝。

函式部署期間會建立下列元件：

Cloud Run 函式
Eventarc 觸發條件
Pub/Sub 主題和訂閱項目

在 Cloud Shell 終端機中執行下列指令，在 menu-item-uploads-$PROJECT_ID 上部署 Cloud Run 函式並設定觸發 bucket：

如要將 Cloud Run 函式直接部署到 Cloud Run，請先部署函式，然後為函式建立觸發條件。

部署 Cloud Run 函式：

gcloud beta run deploy process-thumbnails \
      --source=thumbnail \
      --function process-thumbnails \
      --region $REGION \
      --base-image google-22-full/nodejs20 \
      --no-allow-unauthenticated \
      --project=$PROJECT_ID \
--service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com" \
--set-env-vars=BUCKET_THUMBNAILS=$BUCKET_THUMBNAILS,MENU_SERVICE_URL=$MENU_SERVICE_URL \
  --max-instances=1 \
  --quiet

輸出內容範例：

Done.                                                                                                                                                                                    
Service [process-thumbnails] revision [process-thumbnails-00001-abc] has been deployed and is serving 100 percent of traffic.
Service URL: https://process-thumbnails-000000000.us-east1.run.app

建立觸發條件：

gcloud eventarc triggers create process-thumbnails-trigger \
     --location=$REGION \
     --destination-run-service=process-thumbnails \
    --destination-run-region=$REGION \
     --event-filters="type=google.cloud.storage.object.v1.finalized" \
     --event-filters="bucket=$UPLOAD_BUCKET_NAME" \
     --service-account="${CF_SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

輸出內容範例：

Creating trigger [process-thumbnails-trigger] in project [qwiklabs-gcp-02-53f8532696e1], location [us-east1]...done.                                                                     
WARNING: It may take up to 2 minutes for the new trigger to become active.

如果因權限問題導致觸發部署作業失敗，請稍候片刻，等待上一個步驟的 IAM 變更生效。通常需要 1 到 2 分鐘，然後再次嘗試部署。

錯誤輸出內容範例：

...If you recently started to use Eventarc, it may take a few minutes before all necessary permissions are propagated to the Service Agent...
[...]

在 Cloud 控制台中，檢查為函式建立的 Cloud Run 服務：

在 Cloud 控制台中，查看為函式建立的 Eventarc 觸發條件：

在 Cloud 控制台中，檢查為 Eventarc 觸發條件建立的 Pub/Sub 主題和訂閱：

9. 測試並驗證端對端解決方案

將新相片上傳至 Cloud Storage，並監控管道分析圖片的進度。您將監控 Cloud 函式記錄，測試端對端解決方案。

上傳圖片

將這張圖片儲存到本機電腦
重新命名 1.jpg 檔案
開啟 Cloud Storage 主控台
按一下「menu-item-uploads-...」menu-item-uploads-...bucket
按一下「上傳檔案」
將 1.jpg 上傳至儲存空間 bucket
在 Cloud 控制台中，前往「Cloud Run」。
按一下「process-thumbails」
按一下「記錄」分頁標籤

前往 menu-item-thumbnails-$PROJECT_ID Cloud Storage bucket
確認縮圖值區中已建立縮圖

上傳非食品圖片

如要確認這項功能是否正常運作，請上傳不含「食物」類別物件的圖片。

將這張圖片儲存到本機電腦
將檔案重新命名為 2.jpg
開啟 Cloud Storage 主控台
按一下「menu-item-uploads-...」menu-item-uploads-...bucket
按一下「上傳」檔案
將 2.jpg 上傳至 Storage bucket
在 Cloud 控制台中，前往「Cloud Run」。
按一下「process-thumbails」
按一下「記錄」分頁標籤

10. 恭喜！

恭喜，您已完成本實驗室！

後續步驟：

探索其他 Cymbal Eats 程式碼研究室：

清除所用資源

如要避免系統向您的 Google Cloud 帳戶收取本教學課程所用資源的費用，請刪除含有相關資源的專案，或者保留專案但刪除個別資源。

刪除專案

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