使用 Eventarc 和 Cloud Functions (第 2 代) 從 Cloud Storage 觸發事件處理

1. 總覽

在本研究室中，您將瞭解如何使用 Cloud Storage 值區事件和 Eventarc 觸發事件處理。您將使用 Cloud Functions (第 2 代) 分析資料及處理圖片。這個函式會使用 Google 的 Vision API，並將產生的圖片儲存回 Cloud Storage 值區。

4756e4c218d84e26.png

學習目標

如何建立圖片處理管道。

  • 設定 Storage 值區
  • 建立 Cloud 函式以在 Cloud Storage 中讀取及寫入物件
  • 整合 Vision API 以偵測食物圖片
  • 部署 Cloud 函式
  • 部署 Eventarc 觸發條件
  • 測試和驗證端對端解決方案

必要條件

  • 本研究室假設您熟悉 Cloud 控制台和殼層環境。
  • 擁有 Cloud Storage、Cloud Functions 或 Vision API 之前會很有幫助，但這並非硬性規定。

2. 設定和需求

Cloud 專案設定

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

b35bf95b8bf3d5d8.png

a99b7ace416376c4.png

bd84a6d3004737c5.png

  • 「專案名稱」是這項專案參與者的顯示名稱。這是 Google API 未使用的字元字串。您可以隨時更新。
  • 所有 Google Cloud 專案的專案 ID 均不得重複，而且設定後即無法變更。Cloud 控制台會自動產生一個不重複的字串。但通常是在乎它何在在大部分的程式碼研究室中，您必須參照專案 ID (通常為 PROJECT_ID)。如果您對產生的 ID 不滿意，可以隨機產生一個 ID。此外，您也可以自行嘗試，看看系統是否提供該付款方式。在完成這個步驟後就無法變更，而且在專案期間仍會保持有效。
  • 資訊中的第三個值是專案編號，部分 API 會使用這個編號。如要進一步瞭解這三個值，請參閱說明文件。
  1. 接下來，您需要在 Cloud 控制台中啟用計費功能，才能使用 Cloud 資源/API。執行這個程式碼研究室並不會產生任何費用，如果有的話。如要關閉資源，以免系統產生本教學課程結束後產生的費用，您可以刪除自己建立的資源，或刪除整個專案。Google Cloud 的新使用者符合 $300 美元免費試用計畫的資格。

啟用 Cloud Shell

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

8613854df02635a3.png

環境設定

  1. 在 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=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)")
  1. 啟用研究室所需的 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
  1. 啟用研究室所需的 API。(Qwiklabs 專屬步驟)
gcloud services disable cloudfunctions.googleapis.com
gcloud services enable cloudfunctions.googleapis.com
  1. 複製存放區
git clone https://github.com/GoogleCloudPlatform/cymbal-eats.git && cd cymbal-eats/cloud-functions

3. 設定 Cloud Storage 值區

建立 Storage 值區

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

使用 gsutil mb 指令與不重複的名稱來建立兩個值區：

  1. 上傳最先上傳圖片的值區
  2. 用來儲存生成縮圖的縮圖值區

建立值區以上傳新圖片：

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/...

更新值區權限

更新 Storage 值區權限，授予使用者讀取權限。

使用 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 函式建立自訂服務帳戶以處理縮圖：

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 角色，允許將產生的圖片儲存在縮圖值區：

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，為圖片指派說明標籤。這個函式會檢查說明標籤。如果標籤標識為「食物」的圖片系統會將事件傳送至選單服務，以更新選單項目的圖片和縮圖。

4c3c3b758dba6a9f.png

觸發函式

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

在本研究室中，您會在 Cloud Storage 中決定完物件後，部署並觸發函式。

物件建立完成

「寫入」時，物件建立完成事件會觸發Cloud Storage 物件的 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 回呼。新圖片上傳至值區時，Cloud Storage 會觸發這個函式。

index.js

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

建立儲存空間參考物件

匯入用戶端程式庫後，您必須建立新的儲存空間用戶端，以及應用程式要互動的值區。

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 檔案時，系統會分部分上傳並組合成單一物件。如果是小型物件，請使用單一要求上傳。

下列程式碼會透過單次要求上傳，將圖片上傳至雲端儲存空間。

index.js

const thumbnailImage = await thumbBucket.upload(thumbFile);

7. 整合 Vision API

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

安裝用戶端程式庫

Cloud 用戶端程式庫支援多種熱門的程式設計語言，如要開始使用資料庫，請先安裝用戶端程式庫。

建立圖片註解器用戶端

如要使用官方用戶端 SDK 存取 Google API，請根據 API 的探索文件建立服務物件，這份文件會說明 API 對 SDK 的 API。您需使用憑證，從 Vision API 的探索服務擷取金鑰。

index.js

const client = new vision.ImageAnnotatorClient();

建立 Vision API 要求

Vision API 可在要求內文中以 base64 編碼字串的形式傳送圖片檔內容，可以對圖片檔執行特徵偵測。

建立要求，並使用圖片資源為您的圖片加上註解。傳送至這個 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 函式

這項圖片大小調整服務是 Cymbal Eats 大型系統的一部分。在本節中，您僅會部署與圖片處理功能相關的元件。完整的安裝作業包含用於上傳映像檔的 UI，以及一個用於儲存結果中繼資料的下游要求。本研究室並未安裝這些功能。

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

  • Cloud 函式
  • Cloud Run 服務
  • Eventarc 觸發條件
  • Pub/Sub 主題和訂閱

在 Cloud Shell 終端機中，執行下列指令，在 menu-item-uploads-$PROJECT_ID 上部署含有觸發條件值區的 Cloud 函式：

gcloud functions deploy process-thumbnails \
  --gen2 \
  --runtime=nodejs16 \
  --source=thumbnail \
  --region=$REGION \
  --project=$PROJECT_ID \
  --entry-point=process-thumbnails \
  --trigger-bucket=$UPLOAD_BUCKET \
  --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

如果上傳 Storage 值區發生權限問題導致部署失敗，請等待上一個步驟的 IAM 變更生效。通常需要 1 至 2 分鐘，然後再次重新部署。

輸出範例

Deploying function (may take a while - up to 2 minutes)...done.
[...]

在 Cloud 控制台中，查看已建立的 Cloud 函式：

8148dd29e6757603.png

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

42e970cdd48cae76.png

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

9441995a5cc62e38.png

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

affe089c39ae1465.png

a4c41ede2af300db.png

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

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

上傳合適的圖片

2fdd13b63d6148f4.jpeg

  1. 將此映像檔儲存至本機電腦
  2. 重新命名 1.jpg 檔案
  3. 開啟 Cloud Storage 控制台
  4. 點選「menu-item-uploads-...」menu-item-uploads-...值區
  5. 點選「上傳檔案」
  6. 將 1.jpg 上傳至儲存空間值區
  7. 在 Cloud 控制台中，前往「Cloud Functions」
  8. 按一下「程序縮圖」。
  9. 按一下「LOGS」(記錄) 分頁標籤

7ab4e783e474c90d.png

  1. 前往 menu-item-thumbnails-$PROJECT_ID Cloud Storage 值區
  2. 驗證是否已在縮圖值區中建立縮圖圖片

84d8023782eb3e0c.png

上傳非食物圖片

為了驗證函式是否正常運作，您需要上傳的圖片，且不得包含可歸類為「食物」的物體項目。

3226a24251084b28.jpeg

  1. 將此映像檔儲存至本機電腦
  2. 重新命名 2.jpg 檔案
  3. 開啟 Cloud Storage 控制台
  4. 點選「menu-item-uploads-...」menu-item-uploads-...值區
  5. 點選「上傳檔案」
  6. 將 2.jpg 上傳至儲存空間值區
  7. 在 Cloud 控制台中，前往「Cloud Functions」
  8. 按一下「程序縮圖」。
  9. 按一下「LOGS」(記錄) 分頁標籤

421c36c342fceea8.png

10. 恭喜！

恭喜，您完成了研究室！

下一步：

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

清除所用資源

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

刪除專案

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