建立註冊項目以接收事件

管道

1. 開啟終端機。

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

   gcloud beta eventarc pipelines create PIPELINE_NAME \
       --destinations=DESTINATION_KEY \
       --location=LOCATION

   更改下列內容：

   • PIPELINE_NAME：管道 ID 或完全修飾名稱

   • DESTINATION_KEY：一或多個鍵/值組合，用於設定管道的目的地

     您必須設定其中一個鍵：

     • http_endpoint_uri：目的地 URI。主機可以是可透過虛擬私有雲 (VPC) 網路存取的靜態 IP，或是可透過 Cloud DNS 解析的服務內部網域名稱系統 (DNS) 主機名稱。您也可以視需要設定 http_endpoint_message_binding_template，指定訊息繫結。

       請注意，您可以使用這個鍵指定 Cloud Run 函式、Cloud Run 工作，或是會以 HTTP POST 要求接收事件的 Cloud Run 服務。

     • message_bus：Eventarc Advanced 匯流排的 ID。

     • pubsub_topic：Pub/Sub 主題 ID。

     • workflow：Workflows 工作流程的 ID。

     僅限 http_endpoint_uri (包括 Cloud Run 網址)，您必須設定下列鍵：

     • network_attachment：讓供應商虛擬私有雲網路可與消費者虛擬私有雲網路建立連線的資源。發布事件時，Eventarc Advanced 會使用網路連結，與虛擬私有雲網路中託管的端點建立連線。

       您可以建立網路連結，自動接受任何參照網路連結的 Private Service Connect 介面的連線。在含有目的地資源的相同網路和區域中建立網路附件。

       如果您要使用 DNS 位址將訊息轉送至 Google 目的地 (例如 Cloud Run)，請務必在網路附件中使用的子網路中啟用 私人 Google 存取權，否則無法解析 DNS 位址。

     如要啟用驗證功能，您可以設定下列其中一個金鑰：

     • google_oidc_authentication_service_account：用於產生 OIDC 權杖的服務帳戶電子郵件，可用於許多情境，包括您想自行驗證權杖的端點。您可以選擇設定 google_oidc_authentication_audience，指定此權杖的目標對象。一般來說，這應該與目標管道的網址相符。如未指定，系統會使用整個網址 (包括任何要求參數)。

       請注意，Cloud Run 會對每項要求執行 IAM 檢查，您可以使用 run.routes.invoke 權限，透過下列任一方式設定可存取 Cloud Run 服務的使用者：

       • 將權限授予特定服務帳戶或群組，允許存取服務。所有要求都必須包含 HTTP 授權標頭，其中包含 Google 為某個已授權服務帳戶簽署的 OpenID Connect 權杖。

       • 將權限授予 allUsers，允許未經驗證的存取權。

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

     • oauth_token_authentication_service_account：用於產生 OAuth 權杖的服務帳戶電子郵件地址，通常應僅在呼叫 *.googleapis.com 上託管的 Google API 時使用。您可以視需要設定 oauth_token_authentication_scope 來指定此符記的範圍；否則，預設為 https://www.googleapis.com/auth/cloud-platform。對於Google Cloud 服務，最佳做法是使用 https://www.googleapis.com/auth/cloud-platform 範圍，其中包含所有 Google Cloud API，以及提供精細存取權控管的 Identity and Access Management (IAM)。

       請注意，所有對其他 Eventarc Advanced 匯入器、Pub/Sub 或工作流程的要求，都必須包含 HTTP 授權標頭，其中包含 Google 為某個已授權服務帳戶簽署的 OAuth 權杖。

       進一步瞭解符記類型。

     選用：您可以設定下列一個鍵：

     • output_payload_format_avro_schema_definition
     • output_payload_format_json

     • output_payload_format_protobuf_schema_definition

       請注意，如果您設定輸出格式，也必須指定輸入格式 (請參閱下列 input-payload-format-* 旗標)。

     選用步驟：如果 http_endpoint_uri 不是用來做為目的地鍵，您可以設定下列鍵：

     • project：目的地資源的 Google Cloud 專案 ID；系統預設會使用管道的專案 ID。
     • location：目的地資源的位置。預設會使用管道的所在位置。

   • LOCATION：支援的 Eventarc Advanced 區域

     或者，您也可以設定 gcloud CLI 位置屬性：

     gcloud config set eventarc/location LOCATION
     

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

   • --async 立即從指令傳回，不必等待進行中的作業完成。
   • --crypto-key 可用來指定客戶管理的加密金鑰的完整名稱；如果未指定，系統會使用 Google-owned and managed keys 。
   • --logging-config 可用來設定記錄層級，該層級必須是下列其中一個：NONE、DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT、EMERGENCY。

   • --mediations 可套用轉換；transformation_template 是唯一支援的範本，且每個管道僅支援一個中介服務；例如：

     --mediations=transformation_template='message.removeFields(["id\ ","credit_card_number","age"])'

     請注意，如果您要套用轉換，則必須使用下列其中一個旗標來指定輸入格式。

   • 指定輸入格式時，請使用下列其中一種格式：

     • --input-payload-format-avro-schema-definition
     • --input-payload-format-json
     • --input-payload-format-protobuf-schema-definition

   • --max-retry-attempts、--max-retry-delay 和 --min-retry-delay 到「重試事件」

   例如：

   gcloud beta eventarc pipelines create my-pipeline \
       --destinations=http_endpoint_uri='https://example-endpoint.com',network_attachment=my-network-attachment,oauth_token_authentication_service_account=example-service-account@example-project.gserviceaccount.iam.com,oauth_token_authentication_scope='https://www.googleapis.com/auth/cloud-platform',output_payload_format_avro_schema_definition='{"type": "record","name": "my_record", "fields": [{"name": "my_field", "type":"string"}]}' \
       --input-payload-format-avro-schema-definition='{"type":"record", "name": "my_record", "fields": [{"name": "my_field","type": "string"}]}' \
       --location=us-central1 \
       --async
   

   如需更多詳細資訊和範例，請參閱 gcloud CLI 說明文件。

註冊

1. 開啟終端機。

2. 使用 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=LOCATION

   更改下列內容：

   • ENROLLMENT_NAME：註冊 ID 或完全修飾名稱
   • MATCH_EXPRESSION：使用 CEL比對此註冊的運算式，例如 "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'"
   • PIPELINE_NAME：目標管道 ID 或此註冊項目的完整名稱
   • BUS_NAME：Eventarc Advanced 匯流排的 ID 或完整名稱
   • PROJECT_ID：匯入匯出的 Google Cloud 專案 ID

   • LOCATION：支援的 Eventarc Advanced 區域

     或者，您也可以設定 gcloud CLI 位置屬性：

     gcloud config set eventarc/location LOCATION
     

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

   • --async 立即從指令傳回，不必等待進行中的作業完成

   例如：

   gcloud beta eventarc enrollments create my-enrollment \
       --cel-match="message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'" \
       --destination-pipeline=my-pipeline \
       --message-bus=my-message-bus \
       --message-bus-project=another-google-cloud-project \
       --location=us-central1 \
       --async
   

pipeline

如要建立管道，請使用 projects.locations.pipelines.create 方法。

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

• name：管道的完整資源名稱，格式為 projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME

  更改下列內容：

  • PROJECT_ID：管道專案的 Google Cloud專案 ID
  • LOCATION：管道部署的區域，例如 us-central1
  • PIPELINE_NAME：管道名稱
• LABEL_KEY 和 LABEL_VALUE：選用。標籤鍵/值組合對應表，可協助您整理 Google Cloud 資源。詳情請參閱「什麼是標籤？」
• ANNOTATION_KEY 和 ANNOTATION_VALUE：選用。包含自由格式文字的註解鍵和值組合對應表。您可以使用這些屬性，附加與資源相關的任意資訊。詳情請參閱「註解」。
• LOG_SEVERITY：選用。記錄項目描述的事件最低嚴重性。只能設為以下任一種：NONE、DEBUG、INFO、NOTICE、WARNING、ERROR、CRITICAL、ALERT、EMERGENCY。預設為 NONE。詳情請參閱 LogSeverity。
• destinations：郵件轉寄的目的。僅支援下列其中一個目的地：httpEndpoint、messageBus、topic 或 workflow。詳情請參閱 Destination 目標。例如，取代下列內容：
  • HTTP_URI：目的地 URI。主機可以是可透過虛擬私有雲 (VPC) 網路存取的靜態 IP，或是可透過 Cloud DNS 解析的服務內部 網域名稱系統 (DNS) 主機名稱。您也可以視需要設定 messageBindingTemplate，指定 訊息繫結。
  • networkAttachment：僅適用於 httpEndpoint (包括 Cloud Run 網址)。網路附件資源的完整名稱，格式如下：projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION /networkAttachments/NETWORK_ATTACHMENT_NAME。網路連結是一種資源，可讓供應者虛擬私有雲網路啟動與消費者 VPC 網路的連線，且必須指定。發布事件時，Eventarc Advanced 會使用網路連結，與虛擬私有雲網路中託管的端點建立連線。

    您可以建立網路連結，自動接受任何參照網路連結的 Private Service Connect 介面 的連線。在含有目的地資源的相同網路和區域中建立網路連結。

    如果您要使用 DNS 位址將訊息轉送至 Google 目的地 (例如 Cloud Run)，請務必在網路附件中使用的子網路中啟用 私人 Google 存取權，否則無法解析 DNS 位址。

  • SERVICE_ACCOUNT_EMAIL：服務帳戶電子郵件地址的名稱，用於產生 OIDC 權杖，可用於許多情況，包括您想自行驗證權杖的端點。您可以選擇設定 audience，指定此權杖的目標對象。一般來說，應與目標管道的網址相符。如未指定，系統會使用整個網址 (包括任何要求參數)。

    或者，您也可以使用 oauthToken 指定用於產生 OAuth 權杖的服務帳戶電子郵件地址，但一般來說，只有在呼叫 *.googleapis.com 上代管的 Google API 時，才應使用這項資訊。您可以選擇設定 scope 來指定此權杖的範圍；否則，預設為 https://www.googleapis.com/auth/cloud-platform。對於 Google Cloud服務，最佳做法是使用 https://www.googleapis.com/auth/cloud-platform 範圍 (包含所有 Google Cloud API) 搭配 身分與存取權管理 (IAM)，後者可提供精細的存取權控管功能。

    請注意，所有對其他 Eventarc Advanced 中繼、Pub/Sub 或工作流程的要求，都必須包含 HTTP 授權標頭，其中包含 Google 為某個已授權服務帳戶簽署的 OAuth 權杖。

    進一步瞭解符記類型。

JSON 要求主體：

{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}

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

cat > request.json << 'EOF'
{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}
EOF

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/pipelines?pipeline_id=PIPELINE_NAME"

@'
{
  "name": "projects/PROJECT_ID/regions/LOCATION/pipelines/PIPELINE_NAME",
  "labels": {"LABEL_KEY":"LABEL_VALUE"},
  "annotations": {"ANNOTATION_KEY":"ANNOTATION_VALUE"},
  "loggingConfig": {"logSeverity":"LOG_SEVERITY"},
  "destinations": [{"httpEndpoint": {"uri": "HTTP_URI"},"networkConfig":
  {"networkAttachment": "projects/NETWORK_ATTACHMENT_PROJECT_ID/regions/NETWORK_ATTACHMENT_LOCATION/networkAttachments/NETWORK_ATTACHMENT_NAME"},
  "authenticationConfig": {"googleOidc": {"serviceAccount": "SERVICE_ACCOUNT_EMAIL"}}}]
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/pipelines?pipeline_id=PIPELINE_NAME" | Select-Object -Expand Content

如果成功，回應主體會包含新建立的 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/pipelines/PIPELINE_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

註冊

如要建立註冊，請使用 projects.locations.enrollments.create 方法。

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

• ENROLLMENT_NAME：註冊的顯示名稱，例如 my_enrollment。
• MATCH_EXPRESSION：CEL 運算式，用於識別此註冊適用的訊息。例如：message.type == 'hello-world-type'。
• destination：目標管道的完整資源名稱，格式為 projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME。

  更改下列內容：

  • PROJECT_ID：管道專案的 Google Cloud專案 ID
  • LOCATION：部署管道的區域，例如 us-central1。
  • PIPELINE_NAME：管道名稱
• message_bus：識別訊息來源的匯流程式資源完整名稱，格式為 projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME。

  更改下列內容：

  • BUS_PROJECT_ID：匯入專案的 Google Cloud 專案 ID
  • BUS_LOCATION：公車部署的區域，例如 us-central1
  • BUS_NAME：訊息匯流排的名稱

JSON 要求主體：

{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}

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

cat > request.json << 'EOF'
{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}
EOF

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/enrollments?enrollment_id=ENROLLMENT_NAME"

@'
{
  "display_name": "ENROLLMENT_NAME",
  "cel_match": "MATCH_EXPRESSION",
  "message_bus": "projects/BUS_PROJECT_ID/locations/BUS_LOCATION/messageBuses/BUS_NAME",
  "destination": "projects/PROJECT_ID/locations/LOCATION/pipelines/PIPELINE_NAME"
}
'@  | Out-File -FilePath request.json -Encoding utf8

$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/enrollments?enrollment_id=ENROLLMENT_NAME" | Select-Object -Expand Content

如果成功，回應主體會包含新建立的 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/enrollments/ENROLLMENT_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}