建立註冊項目以接收事件

管道

1. 開啟終端機。

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

   gcloud 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 來指定訊息繫結。

       您可以使用這個金鑰，指定要接收 HTTP POST 要求形式事件的 Cloud Run 服務網址。使用在首次部署 Cloud Run 託管服務時提供的穩定自動指派 run.app URL。或者，您也可以指定BigQuery 資料表，以接收 HTTP POST 要求的形式傳送的事件。定義訊息繫結，建構 BigQuery API 的 HTTP 要求。

       您也可以使用這個目的地類型，為 Cloud Run 函式 (第 1 代和目前版本) 指定 HTTP 端點。為 Cloud Run 函式指定 HTTP 觸發條件時，系統會為函式指派網址，函式可透過該網址接收要求。

     • message_bus，即 Eventarc Advanced 匯流排的 ID。匯流排必須與管道部署在相同專案和區域。

     • pubsub_topic：Pub/Sub 主題的 ID。必須先建立主題，訊息才能傳送至該主題。此外，如果使用主題結構定義，請務必適當轉換事件訊息。

     • workflow—Workflows 工作流程的 ID。 您可以觸發工作流程的執行作業，也就是單次執行工作流程定義中包含的邏輯。工作流程必須部署在與管道相同的專案中。

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

     • 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。對於服務，最佳做法是使用 https://www.googleapis.com/auth/cloud-platform 範圍 (包含所有 Google Cloud API)，以及 Identity and Access Management (IAM)，提供精細的存取權控管。Google Cloud

       請注意，對其他 Eventarc Advanced 匯流排、Pub/Sub 或 Workflows 的所有要求，都必須具備 HTTP Authorization 標頭，其中包含由 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：目的地資源的專案 ID；預設會使用管道的專案 ID。 Google Cloud
     • 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 eventarc pipelines create my-pipeline \
       --destinations=http_endpoint_uri='https://example-endpoint.com',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 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=LOCATION

   更改下列內容：

   • ENROLLMENT_NAME：登錄 ID 或完整名稱
   • ：這個註冊程序的比對運算式 (使用 CEL)，例如 "message.type == 'google.cloud.dataflow.job.v1beta3.statusChanged'"MATCH_EXPRESSION
   • 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 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：管道專案的專案 ID Google Cloud
  • 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：郵件轉寄目的地。(選用) 您可以設定 messageBindingTemplate 來指定訊息繫結。詳情請參閱Destination目標。系統僅支援一個目的地：
  • httpEndpoint：目的地 URI (HTTP_URI)。主機可以是虛擬私有雲 (VPC) 網路中可定址的靜態 IP 位址，也可以是可使用 Cloud DNS 解析的服務內部網域名稱系統 (DNS) 主機名稱。

    舉例來說，您可以指定 Cloud Run 服務網址，該網址會以 HTTP POST 要求的形式接收事件。使用 Cloud Run 代管服務首次部署時提供的自動指派 run.app URL。或者，您也可以指定BigQuery 資料表，以接收 HTTP POST 要求形式的事件。定義訊息繫結，建構 BigQuery API 的 HTTP 要求。

    您也可以使用這個目的地類型，為 Cloud Run 函式 (第 1 代和目前版本) 指定 HTTP 端點。為 Cloud Run 函式指定 HTTP 觸發條件時，系統會為函式指派網址，函式可透過該網址接收要求。

  • messageBus：Eventarc Advanced 匯流排。匯流排必須與管道部署在相同專案和區域。
  • topic：Pub/Sub 主題，必須先在與管道相同的專案中建立。如果使用主題結構定義，請務必適當轉換事件訊息。
  • workflow： 工作流程 工作流程。您可以觸發工作流程的執行作業，也就是單次執行工作流程定義中包含的邏輯。工作流程必須部署在與管道相同的專案中。
• 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 或 Workflows 的要求，都必須含有 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"},
  "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"},
  "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"},
  "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：管道專案的專案 ID Google Cloud
  • 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
}