View a markdown version of this page

自訂事件匯流排的通用目標 - Amazon EventBridge
目標 ARN不支援的動作Parameters批次處理和$events陣列範例：每個事件一個 DynamoDB 項目當 API 呼叫失敗時

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

自訂事件匯流排的通用目標

通用目標直接從訂閱者叫用 AWS API 動作，兩者之間沒有函數。您不會將佇列、主題或函數命名為目標，而是將服務和 API 動作命名，並撰寫 EventBridge 傳送的 API 請求，可以是固定 JSON 或 JSONata 表達式，以從事件建置請求。訂閱者可以將項目寫入 DynamoDB 資料表、將物件放入 Amazon S3 儲存貯體、發佈至 Amazon SNS 主題，或啟動 Step Functions 執行，而路徑中沒有 Lambda 函數。

目標 ARN

通用目標的 TargetArn具有固定形式，不含區域和帳戶：

arn:aws:events:::aws-sdk:service:apiAction

  • 服務是 AWS SDK 服務識別符，不一定是服務的熟悉名稱。例如，Step Functions 是 sfn，而不是 states。可行的範例：sqs、sns、s3、dynamodb、bedrockagentcore。

  • apiAction 是 camelCase 中具有小寫第一個字母的 API 動作名稱：putItem，而不是 PutItem。EventBridge 會像您在 camelCase 的動作索引中撰寫一樣查閱名稱，因此 PutItem 會拒絕該名稱，CreateSubscriber並顯示 api PutItem 對服務 dynamodb 無效的訊息。相同的訊息表示該服務不存在 動作。

例如， arn:aws:events:::aws-sdk:dynamodb:putItem叫用 DynamoDB PutItem， 叫arn:aws:events:::aws-sdk:sns:publish用 Amazon SNS Publish。

不支援的動作

兩種動作不能是訂閱者的目標，並使用表示 API 或整個服務不受支援的訊息來CreateSubscriber拒絕它們。

  • 讀取而非變更狀態的動作，例如名稱開頭為 get、 list或 的動作describe。事件帶有發生的情況，因此目標動作必須變更狀態。EventBridge 會保留封鎖的動作名稱和服務清單，並可以新增到其中，例如，當動作不作為目標時，因此無法保證接受一次的動作；請將建立時間訊息視為授權。

  • EventBridge 發佈動作 eventbridge:putEvents和 eventbridge:putPartnerEvents。若要將事件交付至另一個事件匯流排，請將匯流排 ARN 設定為 TargetArn；自訂事件匯流排和自訂事件匯流排 - Classic 都支援做為自己的目標。請參閱 事件匯流排目標：匯流排至匯流排。

Parameters

通用目標需要 InvokeConfiguration.UniversalTargetParameters。 CreateSubscriber拒絕省略它的訂閱者，或提供不同的參數區塊，例如 SqsParameters。訊息顯示 UniversalTargetParameters 為預期。透過 塑造請求Input；通用目標訂閱者不使用訂閱者的 Transformer，因此請在 中放置任何 JSONata 轉換Input。

Input (必要)

API 請求，做為 JSON 字串或包裝在 中{% %}以產生請求的 JSONata 表達式。使用目標 API 本身參考的成員名稱；適用於 QueueUrl和 SendMessage的 Amazon SQSMessageBody。最多 262，144 個字元。

當您根據 API 要求的欄位建立訂閱者時，Input會檢查固定 JSON，而缺少的欄位會依名稱拒絕。只會Input檢查 JSONata 是否有語法，因為它的結果取決於事件，因此請求目標 API 在交付時間拒絕表面。

InvocationTimeoutSeconds

EventBridge 等待一次 API 呼叫的時間，從 1 秒到 30 秒。預設值為 30。這必須是常值整數；此處不接受 JSONata 表達式。

中的交付角色RoleArn需要您調用之 API 的 IAM 動作，例如無效字母佇列sqs:SendMessage上的 dynamodb:PutItem和 。如需角色的信任政策及其其餘許可，請參閱 自訂事件匯流排的存取控制。

批次處理和$events陣列

EventBridge 每個批次進行一次 API 呼叫，而不是每個事件一次。 會BatchConfiguration設定批次：MaxBatchSize從 1 到 500，MaxBatchWindowInSeconds以及從 0 到 300。批次會在達到大小或視窗經過時關閉，以先發生者為準。

在 JSONata 中Input， $events是批次：其中事件的陣列。批次大小為 1 時， $events.Data.orderId會產生一個事件的值。使用較大的批次，明確地處理陣列，例如使用 $map和 $join，或表達式產生陣列，其中 API 預期字串且交付失敗。

將 MaxBatchSize設為 1 並將 MaxBatchWindowInSeconds設為 0，為每個事件發出一次 API 呼叫。只要Input是固定的 JSON，就會執行此操作，因為批次中每個事件的固定請求都相同，而且批次會產生單一呼叫。

範例：每個事件一個 DynamoDB 項目

下列訂閱者會針對使用 發佈的每個事件，從事件orderId的 欄位取得分割區索引鍵PutRawEvents，將一個項目寫入 DynamoDB 資料表。交付角色需要 資料表dynamodb:PutItem。

aws eventsv2 create-subscriber \
    --name orders-to-dynamodb \
    --event-bus-arn arn:aws:events:us-east-1:111122223333:event-busv2/orders/EXAMPLE1234567890abcdef \
    --invoke-configuration '{
        "TargetArn": "arn:aws:events:::aws-sdk:dynamodb:putItem",
        "RoleArn": "arn:aws:iam::111122223333:role/EventBusDeliveryRole",
        "UniversalTargetParameters": {
            "Input": "{% { \"TableName\": \"orders\", \"Item\": { \"pk\": { \"S\": $events.Data.orderId }, \"total\": { \"N\": $string($events.Data.total) } } } %}"
        }
    }' \
    --batch-configuration MaxBatchSize=1,MaxBatchWindowInSeconds=0 \
    --on-failure-configuration '{ "Arn": "arn:aws:sqs:us-east-1:111122223333:orders-to-dynamodb-dlq" }'

對於使用 發佈的事件PutEvents，相同的欄位位於 下detail：$events.Data.detail.orderId。請參閱 事件結構：資料、中繼資料和系統中繼資料。

當 API 呼叫失敗時

當您建立訂閱者時，EventBridge 會檢查 ARN 的形狀、動作是否存在且未封鎖，以及固定的 Input 攜帶動作的必要欄位，以及表達Input式剖析的 JSONata 。它不會檢查請求中名為 的資源是否存在，或交付角色可以呼叫 動作。這些失敗會在交付時發生，而且每個交付失敗都會在訂閱者的 下重試RetryPolicy，預設為在 300 秒內最多嘗試 5 次。達到限制時，EventBridge 會將記錄寫入errorCode名稱為上次失敗的無效字母佇列。通用目標最常產生的代碼：

  • CUSTOMER_VALIDATION：目標 API 拒絕請求，例如缺少必要欄位或值超出範圍。記錄會攜帶目標 API 自己的錯誤訊息。

  • ACCESS_DENIED：EventBridge 無法擔任交付角色，或該角色不允許對資源呼叫 動作。記錄會指出在 EventBridge 訊息中，指定該角色或資源。

  • RESOURCE_NOT_FOUND：請求中名為 的資料表、主題或其他資源不存在。

  • INPUT_TRANSFORMATION_FAILURE： 中的 JSONata Input 表達式擲出錯誤或沒有產生任何值。

  • THROTTLING：目標 API 限流呼叫。REQUEST_TOO_LARGE：請求超過動作的大小限制；較低的 MaxBatchSize。EXECUTION_TIMEOUT：呼叫未在逾時內傳回。

如需錯誤代碼的完整清單、每個承載的訊息，以及如何重新驅動，請參閱 重試政策和無效字母佇列。開啟訂閱者日誌以查看每次嘗試和傳送的確切請求；請參閱自訂事件匯流排的可觀測性：指標、日誌和 CloudTrail。