建立匯流排和註冊項目，發布及接收事件 (控制台)

建立匯流排和註冊項目，發布及接收事件 (控制台)

進階

本快速入門導覽課程說明如何建立 Eventarc Advanced 匯流排和註冊項目，在專案中發布及接收事件訊息。 Google Cloud

• 匯流排可讓您集中管理系統中的訊息流程，並做為路由器。接收來自訊息來源或提供者發布的事件訊息，並根據註冊條件評估訊息。

• 註冊項目可用於識別特定匯流排的訂閱項目，並定義訊息的比對條件，以便將訊息轉送至一或多個目的地。

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

1. 建立 Artifact Registry 標準存放區。

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

3. 建立 Eventarc Advanced 匯流排。

4. 建立 Eventarc Advanced 註冊。

5. 將事件訊息發布至匯流排。

6. 在 Cloud Run 記錄檔中查看事件資料。

您可以使用 Google Cloud 控制台完成本快速入門導覽課程中的大部分步驟。如要使用 Google Cloud CLI 完成所有步驟，請參閱「建立匯流排和註冊項目來發布及接收事件 (gcloud CLI)」。

事前準備

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Artifact Registry, Cloud Build, Cloud Run, Compute Engine, and Eventarc APIs.

Enable the APIs

1. 本快速入門導覽課程的部分步驟需要使用 gcloud CLI：
   1. 在下列其中一個開發環境中設定 gcloud CLI：

      Cloud Shell

      如要使用已設定 gcloud CLI 的線上終端機，請啟用 Cloud Shell：

      頁面底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。工作階段可能要幾秒鐘的時間才能初始化。

      本機殼層

      如要使用本機開發環境，請按照下列步驟操作：

      1. 安裝 gcloud CLI。
      2. 初始化 gcloud CLI。
   2. 選取 Google Cloud 專案：

      gcloud config set project PROJECT_ID

      將 PROJECT_ID 替換為您的專案名稱。 Google Cloud

   3. 更新 gcloud 元件：

      gcloud components update

   4. 登入帳戶：

      gcloud auth login

   5. 設定本快速入門導覽課程中使用的設定變數：

      REGION=us-central1

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

   如果您不是專案建立者，必須在專案中將必要權限授予適當的主體。舉例來說，主體可以是 Google 帳戶 (適用於使用者) 或服務帳戶 (適用於應用程式和運算工作負載)。

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

   所需權限

   如要取得完成本快速入門所需的權限，請要求管理員為您授予專案的下列 IAM 角色：

   • Cloud Build 編輯器 (roles/cloudbuild.builds.editor)
   • Cloud Run Admin (roles/run.admin)
   • Eventarc 開發人員 (roles/eventarc.developer)
   • Eventarc 訊息匯流排管理員 (roles/eventarc.messageBusAdmin)
   • 記錄檔檢視存取者 (roles/logging.viewAccessor)
   • 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
   • 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
   • 服務帳戶使用者 (roles/iam.serviceAccountUser)
   • 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)

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

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

3. 將專案角色授予 Compute Engine 預設服務帳戶。您需要這些角色，才能建構及部署容器映像檔。
   1. 前往 Google Cloud 控制台的「IAM」頁面。
      

      前往「身分與存取權管理」頁面

   2. 如要修改服務帳戶的角色 (如果該帳戶在資源中已有角色)，請找出含有主體的資料列。

      或

      如要將角色授予資源上沒有任何角色的服務帳戶，請按一下「授予存取權」，然後使用下列格式輸入 Compute Engine 預設服務帳戶的 ID：

      [e-mail]

      將 PROJECT_NUMBER 替換為專案編號。 Google Cloud您可以在 Google Cloud 控制台的「歡迎」頁面找到專案編號。

   3. 按一下對應列中的「編輯主體」。
   4. 按一下 「新增角色」或 「新增其他角色」。
   5. 在「請選取角色」清單中，篩選並選取下列角色：
      • Artifact Registry Writer：上傳 Artifact Registry 構件
      • 記錄寫入者： 將記錄寫入 Cloud Logging
      • 儲存空間物件使用者：存取 Cloud Storage 物件
   6. 按一下 [儲存]。
4. 根據預設，只有專案擁有者、專案編輯者，以及 Cloud Run 管理員和叫用者可以呼叫 Cloud Run 服務。如要設定驗證，請將專案的 Cloud Run Invoker 角色授予服務帳戶。 Google Cloud 為了進行測試，您會將這個服務帳戶附加至 Eventarc Advanced 管道，代表管道的身分。
   1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。
      

      前往「Service accounts」(服務帳戶)

   2. 按一下 「建立服務帳戶」。
   3. 輸入服務帳戶名稱。
   4. 按一下「建立並繼續」。
   5. 在「Select a role」(請選擇角色) 清單中，篩選並選取「Cloud Run Invoker」(Cloud Run 叫用者) 角色。
   6. 按一下 [完成]。

   請注意，您可以透過下列任一方式，設定哪些使用者可以存取 Cloud Run 服務：

   • 授予權限給所選服務帳戶或群組，允許存取服務。所有要求都必須具備 HTTP 授權標頭，其中包含 Google 為其中一個授權服務帳戶簽署的 OpenID Connect 權杖。本快速入門導覽課程就是採用這種方式設定存取權。
   • 授予權限，allUsers允許未經驗證的存取要求。

   詳情請參閱「Cloud Run 的存取權控管」。

建立 Artifact Registry 標準存放區

建立 Artifact Registry 標準存放區，用於儲存容器映像檔。

1. 前往 Google Cloud 控制台的「Repositories」頁面。

   前往「Repositories」(存放區)

2. 按一下 「建立存放區」。

3. 輸入「名稱」，例如 my-repo。

   專案中每個存放區位置的存放區名稱不得重複。

4. 在存放區「格式」中，選取「Docker」。

5. 在「Region」(區域) 清單中，選取「us-central1 (Iowa)」(us-central1 (愛荷華州))。

6. 接受其他所有預設值。

7. 點選「建立」。

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

部署 Cloud Run 服務，記錄事件內容。系統也支援其他事件目的地，例如 Pub/Sub 主題、Workflows 或 HTTP 端點。詳情請參閱「事件供應商和目的地」。

1. 在終端機中複製 GitHub 存放區：

   git clone https://github.com/GoogleCloudPlatform/eventarc-samples.git

2. 變更為包含 Cloud Run 程式碼範例的目錄：

   cd eventarc-samples/eventarc-advanced-quickstart/

3. 建構 Docker 容器映像檔，並將映像檔推送至存放區：

   gcloud builds submit \
       --tag $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1

   將 REPOSITORY 替換為 Artifact Registry 存放區名稱。

4. 將容器映像檔部署至 Cloud Run：

   1. 前往 Google Cloud 控制台的「Cloud Run」頁面。

      前往 Cloud Run

   2. 依序按一下 「Deploy container」(部署容器)>「Service」(服務)。

   3. 選取「透過現有的容器映像檔部署單一修訂版本」。

   4. 在「Container image URL」(容器映像檔網址) 中，按一下「Select」(選取)，指定您先前建立的 Artifact Registry 容器映像檔。

   5. (選用) 您可以變更「服務名稱」，例如變更為 my-service。

   6. 在「Region」(區域) 清單中，選取「us-central1 (Iowa)」(us-central1 (愛荷華州))。

   7. 選取「驗證」中的「需要驗證」。

      這樣一來，服務就只允許經過驗證的叫用。

   8. 在「Ingress」(輸入) 中選取「All」(全部)。

      這樣一來，所有要求 (包括直接從網際網路傳送至 run.app 網址的要求) 都能通過。詳情請參閱「限制 Cloud Run 的網路輸入」。

   9. 接受其他所有預設值。

   10. 按一下「建立」，然後等待部署完成。

建立 Eventarc Advanced 匯流排

匯流排會接收來自訊息來源或供應商發布的事件訊息，並做為訊息路由器。

詳情請參閱建立用於傳送訊息的匯流排。

注意： 每個專案中，一個 Google Cloud 支援的區域可建立一個匯流排。

1. 在 Google Cloud 控制台中，依序前往「Eventarc」>「Bus」(匯流排) 頁面。

   前往「Bus」(匯流排) 頁面

2. 按一下 「建立匯流排」。

3. 在「Create a bus」(建立匯流排) 頁面中執行下列操作：

   1. 輸入「匯流排名稱」，例如 my-bus。
   2. 在「Region」(區域) 清單中，選取「us-central1 (Iowa)」(us-central1 (愛荷華州))。

4. 接受其他所有預設值。

5. 點選「建立」。

建立 Eventarc Advanced 註冊

註冊項目會決定要將哪些訊息轉送至目的地，並指定用於為事件訊息設定目的地的管道。

詳情請參閱「建立註冊項目以接收事件」。

使用 Google Cloud 控制台時，您可以同時建立註冊和管道。

注意： 建立註冊和管道可能需要超過 10 分鐘。

1. 如要建立註冊項目，請在 Google Cloud 控制台中，依序前往「Eventarc」>「Pipelines」(管道) 頁面。

   前往 Pipelines

2. 按一下 「建立管道」。

3. 在「Pipeline details」(管道詳細資料) 窗格中，執行下列操作：

   1. 輸入管道名稱，例如 my-pipeline。
   2. 在「Region」(區域) 清單中，選取「us-central1 (Iowa)」(us-central1 (愛荷華州))。 管道必須與匯流排位於相同區域。
   3. 接受其他所有預設值。
   4. 按一下「繼續」。

4. 在「註冊」窗格中，執行下列操作：

   1. 按一下「新增註冊」。
   2. 輸入「註冊名稱」，例如 my-enrollment。
   3. 在「Eventarc Advanced Bus」(Eventarc Advanced 匯流排) 清單中，選取您先前建立的匯流排。

   4. 在「CEL 運算式」欄位中，使用 CEL 編寫評估運算式。例如：

      message.type == "hello-world-type"
      

   5. 按一下 [完成]。

   6. 按一下「繼續」。

   7. 在「事件中介服務」窗格中，再次按一下「繼續」。

5. 在「目的地」窗格中，執行下列操作：

   1. 在「目的地類型」清單中，選取「Cloud Run 服務 (透過 HTTP)」，然後選取您先前建立的 Cloud Run 服務。

   2. 勾選「啟用驗證」核取方塊。

      1. 在「Auth header」(授權標頭) 清單中，選取「OIDC token」(OIDC 權杖)。

      2. 在「Service account」(服務帳戶) 清單中，選取您先前建立的服務帳戶，該帳戶將叫用目的地服務。這個服務帳戶電子郵件地址用於產生 OIDC 權杖。

6. 點選「建立」。

將事件訊息發布至匯流排

如要直接將訊息發布至匯流排，可以使用 gcloud eventarc message-buses publish 指令，或向 Eventarc Publishing REST API 傳送要求。詳情請參閱「直接發布事件」。

訊息必須採用 CloudEvents 格式，這是以通用方式描述事件資料的規格。data 元素是事件的酬載。這個欄位可填入任何格式正確的 JSON。如要進一步瞭解 CloudEvents 內容屬性，請參閱「事件格式」。

使用 gcloud CLI 和 --event-data 及其他事件屬性標記，將事件發布至 Eventarc Advanced 匯流排：

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"key": "hello-world-data"}' \
    --event-id=hello-world-id-1234 \
    --event-source=hello-world-source \
    --event-type=hello-world-type \
    --event-attributes="datacontenttype=application/json" \
    --location=$REGION

或者，使用 gcloud CLI 和 --json-message 標記，以 JSON 訊息的形式將事件發布至 Eventarc Advanced 匯流排：

gcloud eventarc message-buses publish BUS_NAME \
    --location=$REGION \
    --json-message='{"id": "hello-world-id-1234", "type":
 "hello-world-type", "source":
 "hello-world-source", "specversion": "1.0", "data":
 {"key": "hello-world-data"}}'

發布活動後，您應該會收到「活動發布成功」訊息。

在 Cloud Run 記錄中查看事件資料

將事件發布至 Eventarc Advanced 匯流排後，您可以查看 Cloud Run 服務的記錄，確認事件是否如預期收到。

1. 前往 Google Cloud 控制台的「Cloud Run」頁面。

   前往 Cloud Run

2. 在「服務」頁面中，按一下服務名稱。

3. 按一下 [Logs] (記錄) 分頁標籤。

4. 您可以篩選記錄項目並傳回輸出內容。舉例來說，您可以搜尋 hello-world-data。

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

   2025-02-27 08:36:44.350 EST [2025-02-27 13:36:44,352] INFO in server: Body: b'{"key": "hello-world-data"}'
   

   注意： 如果沒有看到記錄項目，請稍候幾分鐘再重試搜尋。

您已成功建立 Eventarc Advanced 匯流排和註冊項目、將事件訊息發布至匯流排，並在事件接收者服務的記錄檔中驗證預期結果。

清除所用資源

完成本快速入門導覽課程所述工作後，您可以刪除已建立的資源，避免系統繼續計費：

1. 刪除 Artifact Registry 存放區。

2. 刪除 Cloud Run 服務。

3. 刪除 Eventarc Advanced 資源：

   1. 刪除註冊項目。

   2. 刪除管道。

   3. 刪除匯流排。

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

注意：刪除專案會造成以下結果：

• 專案中的所有內容都會遭到刪除。 如果您使用現有專案來進行本文中的工作，刪除專案將一併刪除其中已完成的所有工作。
• 自訂的專案 ID 會消失。當您之前建立這個專案時，可能建立了想要在日後使用的自訂專案 ID。如要保留使用該專案 ID 的網址 (例如 appspot.com 網址)，請刪除在該專案中選取的資源，而不是刪除整個專案。

如果打算探索多種架構、教學課程或快速入門導覽課程，重複使用專案有助於避免超出專案配額限制。

1. In the Google Cloud console, go to the Manage resources page.

   Go to Manage resources

2. In the project list, select the project that you want to delete, and then click Delete.
3. In the dialog, type the project ID, and then click Shut down to delete the project.

後續步驟

• 發布 Google 來源的事件
• 直接發布活動
• 轉換收到的事件
• 設定接收到的事件格式