本頁面由 Cloud Translation API 翻譯而成。

建立匯流排和註冊 (gcloud CLI)，以便發布及接收事件

進階

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

匯流排可讓您集中管理系統中的訊息流程，並充當路由器。它會接收來自訊息來源或由提供者發布的事件訊息，並根據註冊項目進行評估。
註冊可用於識別特定匯流排的訂閱項目，並定義訊息的比對條件，讓訊息能依據這些條件轉送至一或多個目的地。

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

建立子網路並啟用私人 Google 存取權。
建立網路連結。
建立 Artifact Registry 標準存放區。
將事件接收器服務部署至 Cloud Run。
建立 Eventarc Advanced 匯流排。
建立 Eventarc Advanced 註冊。
將事件訊息發布至匯流排。
在 Cloud Run 記錄檔中查看事件資料。

您可以使用 gcloud CLI 完成本快速入門課程。如要使用 Google Cloud 控制台完成步驟，請參閱「建立匯流排和註冊 (控制台)，以便發布及接收事件」一文。

事前準備

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

更新 gcloud 元件：
```
gcloud components update
```

使用自己的帳戶登入：
```
gcloud auth login
```

設定本快速入門導覽課程中使用的設定變數：
```
REGION=REGION
```
將 REGION 替換為巴士支援的位置。

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

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

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

如要取得完成這份快速入門課程所需的權限，請要求管理員為您授予專案的下列 IAM 角色：
- Cloud Build 編輯器 (roles/cloudbuild.builds.editor)
- Cloud Run 管理員 (roles/run.admin)
- Eventarc Developer (roles/eventarc.developer)
- Eventarc 訊息匯流排管理員 (roles/eventarc.messageBusAdmin)
- 記錄檔檢視存取者 (roles/logging.viewAccessor)
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
- 服務帳戶使用者 (roles/iam.serviceAccountUser)
- 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)
如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

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

將專案的下列角色授予 Compute Engine 預設服務帳戶。建構及部署容器映像檔時，需要這些角色：

Artifact Registry Writer：上傳 Artifact Registry 構件
Logs Writer：將記錄寫入 Cloud Logging
Storage Object User：可存取 Cloud Storage 物件

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/artifactregistry.writer
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/logging.logWriter
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member=serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com \
    --role=roles/storage.objectUser

將 PROJECT_NUMBER 替換為您的 Google Cloud專案編號。您可以在 Google Cloud 控制台的「歡迎」頁面上找到專案編號，也可以執行下列指令：

gcloud projects describe PROJECT_ID --format='value(projectNumber)'

根據預設，只有專案擁有者、專案編輯者，以及 Cloud Run 管理員和叫用者可以呼叫 Cloud Run 服務。如要設定驗證，請將 Cloud Run 叫用者角色 (run.invoker) 授予服務帳戶：
1. 建立服務帳戶。為了進行測試，您會將此服務帳戶連結至 Eventarc Advanced 管道，以代表管道的身分。
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
  將 SERVICE_ACCOUNT_NAME 換成服務帳戶的名稱。
2. 將 roles/run.invoker 身分與存取權管理角色授予服務帳戶：
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
    --role=roles/run.invoker
```
請注意，您可以透過下列任一方式設定 Cloud Run 服務的存取權限：
- 將權限授予特定服務帳戶或群組，允許存取服務。所有要求都必須包含 HTTP 授權標頭，其中包含 Google 為其中一個授權服務帳戶簽署的 OpenID Connect 權杖。這是本快速入門導覽課程中的存取權設定方式。
- 授予 allUsers 權限，允許未經驗證的存取權。
詳情請參閱「Cloud Run 的存取權控管」一文。

建立子網路並啟用私人 Google 存取權

除非您建立禁止這項功能的組織政策，否則新 Google Cloud專案一開始會設有預設的虛擬私有雲 (VPC) 網路 (自動模式虛擬私有雲網路)，其中在每個區域都有一個子網路。子網路具有相關聯的 IP 位址範圍。

由於您是使用 DNS 位址將訊息路由至 Cloud Run 目的地，因此必須在網路附件中使用的子網路上啟用私人 Google 存取權，否則無法解析 DNS 位址。如要進一步瞭解私人網路和 Cloud Run，請參閱「接收來自 VPC 網路的要求」。

在專案的預設網路中建立子網路，並使用 --enable-private-ip-google-access 標記啟用私人 Google 存取權：

gcloud compute networks subnets create SUBNET_NAME \
    --network=default \
    --range=10.8.0.0/24 \
    --region=$REGION \
    --enable-private-ip-google-access

將 SUBNET_NAME 替換為子網路名稱，例如 my-subnet。

子網路 IP 範圍不得重複，也不能與虛擬私有雲網路和對等互連虛擬私有雲網路中的其他範圍重疊。如要進一步瞭解子網路類型和有效的子網路範圍，請參閱「子網路」。

建立網路連結

網路連結是一種資源，可讓供應商虛擬私有雲網路與用戶虛擬私有雲網路建立連線。發布事件時，Eventarc Advanced 會使用網路連結，與虛擬私有雲網路中託管的端點建立連線。

在包含事件目的地端點的相同網路和區域中建立網路連結，並自動接受來自任何參照網路連結的 Private Service Connect 介面的連線：

gcloud compute network-attachments create ATTACHMENT_NAME \
   --region=$REGION \
   --connection-preference=ACCEPT_AUTOMATIC \
   --subnets=SUBNET_NAME

將 ATTACHMENT_NAME 替換為網路附件的名稱，例如 my-network-attachment。

建立 Artifact Registry 標準存放區

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

gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=$REGION

將 REPOSITORY 替換為 Artifact Registry 存放區的專屬名稱，例如 my-repo。

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

部署可記錄事件內容的 Cloud Run 服務。這項服務只能透過相同專案內的虛擬私有雲網路存取，而且服務 URL 無法直接存取，因為服務只允許經過驗證的叫用要求。

複製 GitHub 存放區：

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

變更為包含 Cloud Run 範例程式碼的目錄：
```
cd eventarc-samples/eventarc-advanced-quickstart/
```

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

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

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

gcloud run deploy SERVICE_NAME \
    --image $REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY/log-events:v1 \
    --platform managed \
    --ingress internal \
    --no-allow-unauthenticated \
    --region=$REGION

將 SERVICE_NAME 替換為您的服務名稱，例如 my-service。

當您看到 Cloud Run 服務網址時，表示部署作業已完成。請記下這個網址，以便在後續步驟中使用。

建立 Eventarc Advanced 匯流排

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

詳情請參閱「建立匯流程來轉送訊息」。

使用 gcloud beta eventarc message-buses create 指令，在專案中建立 Eventarc Advanced 匯流排：

gcloud beta eventarc message-buses create BUS_NAME \
    --location=$REGION

將 BUS_NAME 替換為巴士的 ID 或完整修飾 ID，例如 my-bus。

建立 Eventarc Advanced 註冊

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

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

使用 gcloud CLI 時，您必須先建立管道，再建立註冊：

使用 gcloud beta eventarc pipelines create 指令建立管道：
```
gcloud beta eventarc pipelines create PIPELINE_NAME \
    --destinations=http_endpoint_uri='CLOUD_RUN_SERVICE_URL',network_attachment=ATTACHMENT_NAME,google_oidc_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --location=$REGION
```
更改下列內容：
- PIPELINE_NAME：管道 ID 或完整修飾名稱。
- CLOUD_RUN_SERVICE_URL：Cloud Run 服務的完整網址，例如 https://SERVICE_NAME-abcdef-uc.a.run.app。這是事件訊息的目的地。
請注意，google_oidc_authentication_service_account 鍵會指定服務帳戶電子郵件地址，用於產生 OIDC 權杖。

使用 gcloud beta eventarc enrollments create 指令建立註冊：

gcloud beta eventarc enrollments create ENROLLMENT_NAME \
    --cel-match=MATCH_EXPRESSION \
    --destination-pipeline=PIPELINE_NAME \
    --message-bus=BUS_NAME \
    --message-bus-project=PROJECT_ID \
    --location=$REGION

更改下列內容：

ENROLLMENT_NAME：註冊 ID 或完全修飾名稱。
MATCH_EXPRESSION：使用 CEL比對此註冊的運算式，例如 "message.type == 'hello-world-type'"。

將事件訊息發布至匯流排

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

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

以下是直接將事件發布至 Eventarc Advanced 匯流排的範例：

範例 1

您可以使用 gcloud CLI 和 --event-data 及其他事件屬性旗標，將事件發布至匯流排：

gcloud beta 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

範例 2

您可以使用 gcloud CLI 和 --json-message 旗標，將事件發布至匯入器做為 JSON 訊息：

gcloud beta 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"}}'

發布事件後，您應該會收到「Event published successfully」(事件已成功發布) 訊息。

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

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

使用 gcloud logging read 指令篩選記錄項目並傳回輸出內容：
```
gcloud logging read 'textPayload: "hello-world-data"'
```

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

insertId: 670808e70002b5c6477709ae
labels:
instanceId: 007989f2a10a4a33c21024f2c8e06a9de65d9b4fdc2ee27697a50379b3fab2f975b9233dc357d50b06270829b9b479d5a1ee54a10fa2cb2d98c5f77a0895e2be0f9e6e4b20
logName: projects/PROJECT_ID/logs/run.googleapis.com%2Fstderr
receiveTimestamp: '2024-10-10T17:03:35.424659450Z'
resource:
labels:
...
type: cloud_run_revision
textPayload: "[2024-10-21 15:33:19,581] INFO in server: Body: b'{\"value\":\"hello-world-data\"\
  }'"
timestamp: '2024-10-10T17:03:35.177606Z'

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

清除所用資源

完成本快速入門課程中說明的工作後，您可以刪除已建立的資源，避免系統繼續向您收取費用：

刪除虛擬私有雲子網路。
刪除 VPC 網路連結。
刪除 Artifact Registry 存放區。
刪除 Cloud Run 服務。
刪除 Eventarc Advanced 資源：
1. 刪除註冊項目。
2. 刪除管道。
3. 刪除匯流排。

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

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID