發布 Google 來源的事件

進階

您可以建立 GoogleApiSource 資源，為特定 Eventarc Advanced 匯流排啟用 Google 來源事件的收集和發布功能。

Google 來源的事件是由未經中介的事件直接觸發，例如建立 Cloud Run 函式，或是 Dataflow 工作狀態變更。詳情請參閱「Eventarc 支援的 Google 事件類型」。

重要事項： Google 來源的事件不包括透過 Cloud 稽核記錄產生記錄時觸發的事件。

注意事項：

• 根據預設，系統會從 Google Cloud 專案收集事件，其中包含GoogleApiSource資源。您也可以使用 gcloud CLI，從與 GoogleApiSource 資源位於同一機構的多個專案收集事件。詳情請參閱本文「從多個專案發布事件」一節。
• 您可以將事件發布至與 GoogleApiSource 資源所在專案不同的 Google Cloud 專案 中的匯流排。您可以使用 gcloud CLI 或傳送要求至 Eventarc API (但無法透過 Google Cloud 控制台) 設定這項功能。
• 每個專案在每個區域最多只能有 1 個資源。GoogleApiSource 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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 Eventarc and Eventarc Publishing APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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 Eventarc and Eventarc Publishing APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

gcloud

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Eventarc and Eventarc Publishing APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com

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.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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.

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

Verify that billing is enabled for your Google Cloud project.

Enable the Eventarc and Eventarc Publishing APIs:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

gcloud services enable eventarc.googleapis.com eventarcpublishing.googleapis.com

啟用 Google 來源事件

如要發布 Google 來源的事件，您必須建立 GoogleApiSource 資源。這項資源代表特定 Eventarc Advanced 匯流排的特定 Google Cloud 專案中，Google API 事件的訂閱項目。

您可以透過下列方式啟用發布 Google 來源事件：

• 在 Google Cloud 控制台
• 在終端機或 Cloud Shell 中使用 Google Cloud CLI

• 傳送要求至 Eventarc API

控制台

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

   前往 Bus

2. 您可以建立巴士，或在更新巴士時按一下 「編輯」。

3. 在「編輯匯流排」頁面中，如要新增訊息來源，請按一下 「新增來源」。

   1. 在「新增訊息來源」窗格中，針對 Google API 訊息供應商，接受預設的 google-api-source 或輸入其他訊息來源名稱。
   2. 點選「建立」。

4. 按一下 [儲存]。

gcloud

1. 開啟終端機。

2. 您可以使用 gcloud eventarc google-api-sources create 指令啟用 Google 來源事件：

   gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
       --destination-message-bus=BUS_NAME \
       --destination-message-bus-project=BUS_PROJECT_ID

   更改下列內容：

   • GOOGLE_API_SOURCE_NAME：GoogleApiSource 資源的 ID 或完整識別碼，代表特定匯流排的 Google API 事件訂閱項目
   • BUS_NAME：您要訂閱 Google API 事件的匯流排 ID 或完整識別碼
   • BUS_PROJECT_ID：匯流排的 Google Cloud 專案 ID

   選用：您也可以使用下列標記：

   • --async，讓指令立即傳回，不必等待執行中的作業完成。
   • --crypto-key，指定客戶管理的加密金鑰的完整名稱；如未指定，則使用 Google-owned and managed keys 。
   • --logging-config，設定記錄層級，必須是下列其中一個值：NONE、DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT、EMERGENCY。詳情請參閱「LogSeverity」。

REST API

如要啟用 Google 來源事件，請使用 projects.locations.googleApiSources.create 方法。

使用任何要求資料之前，請先替換以下項目：

• GOOGLE_API_SOURCE_NAME：GoogleApiSource 資源的顯示名稱，代表特定匯流排的 Google API 事件訂閱項目，例如 my_google_source。
• LABEL_KEY 和 LABEL_VALUE：選用。標籤鍵/值組合對應，可協助您整理 Google Cloud 資源。詳情請參閱「什麼是標籤？」
• ANNOTATION_KEY 和 ANNOTATION_VALUE：選用。任意格式文字的註解鍵/值組合對應。您可以使用這些標籤，附加與資源相關的任意資訊。詳情請參閱「註解」一節。
• DESTINATION：Eventarc Advanced 匯流排的完整 ID，Google 來源事件應以 projects/PROJECT_NAME/locations/LOCATION/messageBuses/BUS_NAME 格式發布至該匯流排。詳情請參閱「建立訊息路由匯流排」。
• ENCRYPT_KEY：選用。GoogleApiSource資源應使用的 Cloud KMS 金鑰，用於加密資料，格式為 projects/PROJECT_NAME/locations/LOCATION/keyRings/RING_NAME/cryptoKeys/KEY_NAME。詳情請參閱「使用客戶管理的加密金鑰」。
• PROJECT_ID：要在其中建立 GoogleApiSource 資源的專案 ID。 Google Cloud
• LOCATION：建立 GoogleApiSource 資源的支援區域，例如 us-central1。
• LOG_SEVERITY：選用。記錄項目所述事件的最低嚴重程度。只能設定為NONE、DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT 或 EMERGENCY。預設值為 NONE。詳情請參閱 LogSeverity。

JSON 要求主體：

{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

cat > request.json << 'EOF'
{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
EOF

接著，請執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources?googleApiSourceId=GOOGLE_API_SOURCE_NAME"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中。 在終端機中執行下列指令，在目前目錄中建立或覆寫這個檔案：

@'
{
  "displayName": "GOOGLE_API_SOURCE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "destination": "DESTINATION",
  "cryptoKeyName": "ENCRYPT_KEY",
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"}
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，請執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources?googleApiSourceId=GOOGLE_API_SOURCE_NAME" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求主體貼到這項工具中，並完成其他必填欄位，然後按一下「Execute」(執行)。

如果成功，回應主體會包含新建立的 Operation 例項：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

系統現在會收集與 GoogleApiSource 資源位於相同 Google Cloud 專案的 Google 來源事件，並發布至匯流排。

停用 Google 來源相關事件

如要禁止特定Google Cloud 專案中的 Google 來源將事件發布至 Eventarc Advanced 匯流排，請刪除 GoogleApiSource 資源。

您可以透過下列方式停用發布 Google 來源的事件：

• 在 Google Cloud 控制台
• 在終端機或 Cloud Shell 中使用 gcloud CLI

• 傳送要求至 Eventarc API

控制台

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

   前往「巴士詳細資料」

2. 按一下「編輯」。

3. 在「編輯匯流排」頁面中，如要刪除 Google API 訊息提供者，請按一下「google-api-source」訊息來源 (或您為其指定的名稱) 的「刪除資源」。

4. 在「Delete resource」(刪除資源) 提示中，按一下「Confirm」(確認)。

5. 按一下 [儲存]。

gcloud

1. 開啟終端機。

2. 您可以使用 gcloud eventarc google-api-sources delete 指令停用 Google 來源事件：

   gcloud eventarc google-api-sources delete GOOGLE_API_SOURCE_NAME \
       --location=REGION

   更改下列內容：

   • GOOGLE_API_SOURCE_NAME：GoogleApiSource資源的 ID 或完整 ID
   • REGION：GoogleApiSource 資源的位置

REST API

如要停用 Google 來源事件，請使用 projects.locations.googleApiSources.delete 方法。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_ID：建立 GoogleApiSource 資源的 Google Cloud 專案 ID。
• LOCATION：建立 GoogleApiSource 資源的區域，例如 us-central1。
• GOOGLE_API_SOURCE_NAME：要刪除的 GoogleApiSource 資源名稱。

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://eventarc.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

如果成功，回應主體會包含新建立的 Operation 例項：

{
  "name": "projects/PROJECT_ID/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.eventarc.v1.OperationMetadata",
    "createTime": "2024-01-25T17:17:45.782370139Z",
    "target": "projects/PROJECT_ID/locations/LOCATION/googleApiSources/GOOGLE_API_SOURCE_NAME",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

系統不會再收集及發布與已刪除 Google Cloud 資源位於同一GoogleApiSource專案的 Google 來源事件。

從多個專案發布事件

預先發布版 — Publish events from multiple projects

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

如要從多個 Google Cloud 專案收集及發布 Google 來源事件，您必須建立GoogleApiSource Google Cloud 資源，且專案必須與 GoogleApiSource 資源位於同一個機構。如要進一步瞭解機構，請參閱資源階層。

注意事項：

• 如要設定從多個專案發布事件，必須使用 gcloud CLI，且不會顯示在 Google Cloud 控制台中。
• 如果含有 GoogleApiSource 資源的專案遷移至其他機構，從多個專案發布事件將無法正常運作。您必須更新或重新建立 GoogleApiSource 資源。

1. 授予 Eventarc 服務代理適當的 IAM 角色

如要在機構層級收集事件，請使用 gcloud organizations add-iam-policy-binding 指令，授予 Eventarc 服務代理程式適當的 Identity and Access Management (IAM) 角色：

gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
    --member="SERVICE_AGENT_EMAIL" \
    --role="roles/eventarc.multiProjectEventCollector"

更改下列內容：

• ORGANIZATION_ID：您的機構資源 ID。

• SERVICE_AGENT_EMAIL：您要在當中建立 GoogleApiSource 資源的專案中，Eventarc 主要服務代理程式的電子郵件地址。電子郵件地址的格式如下：

  [e-mail]
  

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

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

2. 從所有專案或專案清單發布

如要從多個專案中的 Google 來源發布事件，請使用下列任一方式執行 gcloud eventarc google-api-sources create 指令：

• 從與 GoogleApiSource 資源位於同一機構的所有 Google Cloud 專案發布：

  gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
      --location=REGION \
      --destination-message-bus=BUS_NAME \
      --destination-message-bus-project=BUS_PROJECT_ID \
      --organization-subscription

• 從與 GoogleApiSource 資源位於同一個機構的專案清單 Google Cloud 發布：

  gcloud eventarc google-api-sources create GOOGLE_API_SOURCE_NAME \
      --location=REGION \
      --destination-message-bus=BUS_NAME \
      --destination-message-bus-project=BUS_PROJECT_ID \
      --project-subscriptions=LIST_OF_PROJECTS

  更改下列內容：

  • GOOGLE_API_SOURCE_NAME：GoogleApiSource資源的 ID 或完整 ID
  • REGION：GoogleApiSource 資源的位置
  • BUS_NAME：您要訂閱 Google API 事件的匯流排 ID 或完整識別碼
  • BUS_PROJECT_ID：匯流排的 Google Cloud 專案 ID
  • LIST_OF_PROJECTS：以半形逗號分隔的Google Cloud 專案 ID 或專案編號清單。您可以在同一份清單中同時加入 ID 和號碼。如要從包含 GoogleApiSource 資源的Google Cloud 專案發布事件，必須在清單中明確加入專案 ID 或編號。

後續步驟

• 快速入門導覽課程：從 Google 來源發布事件
• 直接發布活動
• 設定接收到的事件格式
• 轉換收到的事件