將事件發布至 BigQuery 資料表

將事件發布至 BigQuery 資料表

精確

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

• 匯流排可做為中央路由器，接收來自事件來源的訊息，或由提供者發布的訊息。

• 註冊會透過處理管道，將匯流排收到的訊息轉送至一或多個目的地。

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

1. 建立 BigQuery 資料表。

2. 建立 Eventarc Advanced 匯流排。

3. 建立 Eventarc Advanced 註冊項目。

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

5. 查看 BigQuery 資料表中的事件資料。

您可以使用 gcloud CLI 和 bq 指令列工具完成本快速入門導覽課程。

事前準備

貴機構定義的安全性限制，可能會導致您無法完成下列步驟。如需疑難排解資訊，請參閱「在受限的 Google Cloud 環境中開發應用程式」。

登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
• 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

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

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

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

確認專案已啟用計費功能 Google Cloud 。

啟用 BigQuery 和 Eventarc API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

安裝 Google Cloud CLI。

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

執行下列指令，初始化 gcloud CLI：

gcloud init

建立或選取 Google Cloud 專案。

選取或建立專案所需的角色

• 選取專案：選取專案時，不需要具備特定 IAM 角色，只要您已獲授角色，即可選取任何專案。
• 建立專案：如要建立專案，您需要「專案建立者」角色 (roles/resourcemanager.projectCreator)，其中包含 resourcemanager.projects.create 權限。瞭解如何授予角色。

注意：如果您不打算保留在這項程序中建立的資源，請建立新專案，而不要選取現有專案。完成這些步驟後，您就可以刪除專案，並移除與該專案相關聯的所有資源。

• 建立 Google Cloud 專案：

  gcloud projects create PROJECT_ID

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

• 選取您建立的 Google Cloud 專案：

  gcloud config set project PROJECT_ID

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

確認專案已啟用計費功能 Google Cloud 。

啟用 BigQuery 和 Eventarc API：

啟用 API 時所需的角色

如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

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

1. 更新 gcloud 元件：

   gcloud components update

2. 登入帳戶：

   gcloud auth login

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

   REGION=REGION

   將 REGION 替換為公車的支援位置，例如 us-central1。

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

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

   所需權限

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

   • BigQuery 資料編輯者 (roles/bigquery.dataEditor)
   • Eventarc 開發人員 (roles/eventarc.developer)
   • Eventarc 訊息匯流排管理員 (roles/eventarc.messageBusAdmin)
   • 記錄檔檢視存取者 (roles/logging.viewAccessor)
   • 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
   • 服務帳戶管理員 (roles/iam.serviceAccountAdmin)
   • 服務帳戶使用者 (roles/iam.serviceAccountUser)
   • 服務使用情形管理員 (roles/serviceusage.serviceUsageAdmin)

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

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

5. 如要授予 Eventarc Advanced 更新 BigQuery 資料表屬性所需的權限，請管理員將專案的 Google Cloud 「BigQuery 資料編輯者」 (roles/bigquery.dataEditor) IAM 角色授予服務帳戶：
   1. 建立服務帳戶。為進行測試，您會將這個服務帳戶附加至 Eventarc Advanced 管道，代表管道的身分。

      gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

      將 SERVICE_ACCOUNT_NAME 替換為服務帳戶的名稱。
   2. 將 roles/bigquery.dataEditor IAM 角色授予服務帳戶：

      gcloud projects add-iam-policy-binding PROJECT_ID \
          --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" \
          --role=roles/bigquery.dataEditor

建立 BigQuery 資料表

建立 BigQuery 資料表做為事件目的地。系統也支援其他事件目的地，例如 Pub/Sub 主題、工作流程或其他 HTTP 端點。詳情請參閱「事件供應商和目的地」。

建立 BigQuery 資料表前，請先建立「資料集」(做為資料表的頂層容器) 和資料表「結構定義」。

1. 如要建立新的資料集，請使用 bq mk 指令並加上 --dataset 旗標。

   bq --location=$REGION mk --dataset DATASET_ID

   將 DATASET_ID 替換為 BigQuery 資料集的專屬名稱，例如 my_dataset。

2. 在終端機中，建立名為 my-schema.json 的新檔案。

3. 將下列結構定義複製並貼到新檔案中，然後儲存檔案。

   [
       {
           "name": "name",
           "type": "STRING",
           "mode": "REQUIRED"
       },
       {
           "name": "age",
           "type": "INTEGER",
           "mode": "NULLABLE"
       }
   ]

4. 如要建立資料表，請使用 bq mk 指令搭配 --table 標記。

   bq mk --table PROJECT_ID:DATASET_ID.TABLE_ID my-schema.json

   將 TABLE_ID 換成 BigQuery 資料表的專屬名稱，例如 my-table。

建立 Eventarc Advanced 匯流排

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

詳情請參閱「建立訊息路由匯流排」。

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

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

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

將 BUS_NAME 替換為匯流排的 ID 或完整名稱，例如 my-bus。

建立 Eventarc Advanced 註冊項目

註冊項目會決定要將哪些訊息轉送至目的地，並指定用於為事件訊息設定目的地的管道。在本例中，目標目的地是 BigQuery API 端點。

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

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

使用 gcloud CLI 時，您會先建立管道，然後建立註冊：

1. 使用 gcloud eventarc pipelines create 指令建立管道：

   gcloud eventarc pipelines create PIPELINE_NAME \
       --destinations=http_endpoint_uri='https://bigquery.googleapis.com/bigquery/v2/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID/insertAll',http_endpoint_message_binding_template='{"headers": headers.merge({"content-type":"application/json"}), "body": {"rows":[{"json":message.data}]}}',oauth_token_authentication_service_account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com \
       --input-payload-format-json= \
       --location=$REGION

   將 PIPELINE_NAME 替換為管道的 ID 或完整名稱，例如 my-pipeline。

   注意事項：

   • http_endpoint_message_binding_template 鍵會將事件轉換為 API 預期的格式。定義訊息繫結時，您必須設定輸入格式，才能存取酬載。
   • oauth_token_authentication_service_account 鍵會指定服務帳戶電子郵件地址。這個電子郵件地址用於產生 OAuth 權杖，一般來說，只有在呼叫 *.googleapis.com 上託管的 Google API 時才應使用。
   • input-payload-format-json 旗標指定管道的輸入酬載格式為 JSON，任何不符合此格式的訊息都會視為持續性錯誤。

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

   gcloud 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 或完整名稱，例如 my-enrollment。

   • MATCH_EXPRESSION：使用 CEL 的註冊比對運算式，例如：

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

將事件訊息發布至匯流排

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

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

以下範例說明如何直接將事件發布至 Eventarc Advanced 匯流排：

範例 1

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

gcloud eventarc message-buses publish BUS_NAME \
    --event-data='{"name": "my-name", "age": "20"}' \
    --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 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":
 {"name": "my-name", "age": "20"}}'

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

查看 BigQuery 資料表中的事件資料

將事件發布至 Eventarc Advanced 匯流排後，您可以使用 bq query 指令，確認 BigQuery 資料表是否新增了資料列。

bq query \
    --use_legacy_sql=false \
    'SELECT
      *
    FROM
      `PROJECT_ID.DATASET_ID.TABLE_ID`
    LIMIT
      10;'

您已成功建立 Eventarc Advanced 匯流排和註冊項目、將事件訊息發布至匯流排，並查詢 BigQuery 資料表，確認結果符合預期。

清除所用資源

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

1. 刪除 BigQuery 資料表。

2. 刪除 BigQuery 資料集。

3. 刪除 Eventarc Advanced 資源：

   1. 刪除註冊項目。

   2. 刪除管道。

   3. 刪除匯流排。

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

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

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

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

刪除 Google Cloud 專案：

gcloud projects delete PROJECT_ID

後續步驟

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