直接發布事件

進階

您可以使用 Google Cloud CLI，或向 Eventarc Publishing REST API 發出要求，以支援的格式將 CloudEvents 事件直接發布至 Eventarc Advanced 匯流排。您也可以使用Eventarc 用戶端程式庫，透過支援的語言存取 Eventarc API。

事前準備

開始之前，請確認您已完成下列步驟：

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

直接發布

您直接發布的事件訊息必須符合 CloudEvents 規格。

gcloud

1. 開啟終端機。

2. 您可以使用 gcloud eventarc message-buses publish 指令，將事件發布至匯流排。例如：

   gcloud eventarc message-buses publish BUS_NAME \
       --avro-message=AVRO_MESSAGE

   或：
   gcloud eventarc message-buses publish BUS_NAME \
       --json-message=JSON_MESSAGE

   或：
   gcloud eventarc message-buses publish BUS_NAME \
       --event-data=DATA_PAYLOAD \
       --event-id=EVENT_ID \
       --event-source=EVENT_SOURCE \
       --event-type=EVENT_TYPE \
       --event-attributes=EVENT_ATTRIBUTE

   更改下列內容：

   • BUS_NAME：要發布事件的匯流排 ID 或完整 ID。

   您只能使用下列其中一種方法：

   • AVRO_MESSAGE：Avro 格式的事件訊息，請參閱這份規格。
   • JSON_MESSAGE：JSON 格式的事件訊息，請參閱這份規格。
   • DATA_PAYLOAD：已發布事件的資料。

   如果使用 --event-data 旗標，也必須使用下列項目：

   • EVENT_ID：事件 ID。事件產生者必須確保每個不同的事件都有不重複的 source + id。
   • EVENT_SOURCE：已發布事件的事件來源。
   • EVENT_TYPE：與原始事件相關的事件類型。

   使用 --event-data 標記時，您可以視需要使用下列項目：

   • EVENT_ATTRIBUTE：已發布事件的屬性。 如要新增更多屬性，可以重複使用 --event-attributes 標記。

     請注意，事件可能包含任意數量的其他自訂 CloudEvents 屬性，且名稱各不相同 (也稱為擴充屬性)。

範例：

gcloud eventarc message-buses publish my-bus \
    --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"

gcloud eventarc message-buses publish my-bus --json-message='{
    "specversion" : "1.0",
    "type" :"com.example.someevent",
    "source" : "google.cloud.storage.object.v1.finalized",
    "id" : "A234-1234-1234",
    "time" : "2024-04-05T17:31:00Z",
    "bucket" : "bucketName",
    "datacontenttype" : "application/json",
    "data":{"key": "value"}
}'

REST API

如要將事件發布至匯流排，請使用 projects.locations.messageBuses.publish 方法。

注意： 在要求主體的 ProtoMessage 中，只有當酬載是特定 CloudEvent 訊息類型時，protoData 欄位才能正常運作，無法用於任意通訊協定緩衝區訊息。如果是其他通訊協定緩衝區類型，您必須將 proto 訊息序列化為位元組，並改用 binaryData 欄位。

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

• 匯流排的完整資源名稱，格式為 projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME

  更改下列內容：

  • PROJECT_ID：公車專案的 Google Cloud 專案 ID。
  • LOCATION：部署匯流排的區域，例如 us-central1。
  • BUS_NAME：要發布事件的匯流排名稱。
• SPEC_VERSION：事件使用的 CloudEvents 規格版本，例如 1.0。
• EVENT_TYPE：與原始事件相關的事件類型。
• EVENT_SOURCE：已發布事件的事件來源。
• EVENT_ID：事件 ID。 製作者必須確保每個不同活動的 source + id 都是不重複的。
• CONTENT_TYPE (選用)：data 值的內容類型。如果 JSON 格式的事件沒有 datacontenttype 屬性，系統會假設資料是符合 application/json 媒體類型的 JSON 值。
• DATA_PAYLOAD (選用)：事件酬載，已編碼為 datacontenttype 指定的媒體格式，並遵守 dataschema (如有這些屬性)。

JSON 要求主體：

{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}

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

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'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
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://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish"

PowerShell (Windows)

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

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

@'
{
"jsonMessage":
  "{\"specversion\":\"SPEC_VERSION\",
  \"type\":\"EVENT_TYPE\",
  \"source\":\"EVENT_SOURCE\",
  \"id\":\"EVENT_ID\",
  \"datacontenttype\":\"CONTENT_TYPE\",
  \"data\":\"DATA_PAYLOAD\"}"
}
'@  | 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://eventarcpublishing.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/messageBuses/BUS_NAME:publish" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

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

如果成功，伺服器會傳回 HTTP 200 OK 狀態碼，以及 JSON 格式的空白回應主體：

200 OK

{}

後續步驟

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