View a markdown version of this page

自定义事件总线的通用目标 - 亚马逊 EventBridge
目标 ARN不支持的操作参数批处理和 $ events 数组示例：每个事件一个 DynamoDB 项目当 API 调用失败时

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

自定义事件总线的通用目标

通用目标直接从订阅者那里调 AWS 用 API 操作，中间没有函数。与其将队列、主题或函数命名为目标，不如命名服务和 API 操作，然后编写 EventBridge 发送的 API 请求，可以是固定的 JSON，也可以是根据事件生成请求的 JSONata 表达式。订阅者可以将项目写入 DynamoDB 表、将对象放入 Amazon S3 存储桶、发布到 Amazon SNS 主题或在路径中没有 Lambda 函数的情况下开始执行步进函数。

目标 ARN

通用目标采用固定形式，TargetArn没有地区也没有账户：

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

  • service是 AWS SDK 服务标识符，它并不总是服务熟悉的名称。例如，步进函数不是sfnstates。有效的示例：sqs、sns、s3、dynamodb、bedrockagentcore。

  • apiAction是 camelCase 中的 API 操作名称，首字母为小写：putItem，不是。PutItem EventBridge 按你在操作索引（CamelCase 中）中所写的名称来查找名称，因此PutItem被拒绝，CreateSubscriber并显示消息 “api 对服务 PutItem dynam odb 无效”。相同的消息表示该服务不存在该操作。

例如，arn:aws:events:::aws-sdk:dynamodb:putItem调用 DynamoDB，然后arn:aws:events:::aws-sdk:sns:publish调用 Amazon SN PutItem S。Publish

不支持的操作

两种操作不能成为订阅者的目标，它们CreateSubscriber会通过一条说不支持 API 或整个服务的消息来拒绝他们。

  • 读取而不是更改状态的操作，例如名称以getlist、或开头的操作describe。事件携带已发生的事情，因此目标操作必须更改状态。 EventBridge 保留被屏蔽的操作名称和服务列表并可以添加到该列表中，例如，当某个操作未按目标的要求运行时，因此不能保证曾经被接受的操作永远无法保证；将创建时消息视为权限。

  • EventBridge 发布操作eventbridge:putEvents和eventbridge:putPartnerEvents。要将事件传送到另一个事件总线，请将总线 ARN 设置为TargetArn；自定义事件总线和自定义事件总线-Classic 本身都支持作为目标。请参阅事件总线目标：总线到总线。

参数

一个普遍的目标需要InvokeConfiguration.UniversalTargetParameters。CreateSubscriber拒绝省略该参数或提供其他参数块（例如）的订阅者。SqsParameters消息说UniversalTargetParameters是预料之中的。调整请求Input；通用目标订阅者不使用订阅者的请求Transformer，因此请进行任何 JSonata 转换。Input

Input（必需）

API 请求，以 JSON 字符串或包装在其中的 JSONata 表达式{% %}的形式生成请求。使用目标 API 自己的参考中的成员名称；对于 Amazon SQSSendMessage，则为QueueUrl和MessageBody。最多 262,144 个字符。

当您根据 API 要求的字段创建订阅者时，系统会检查固定的 JSONInput，缺失的字段会按名称拒绝。Input仅检查 JSonata 的语法，因为其结果取决于事件，因此目标 API 拒绝的请求会在交付时出现。

InvocationTimeoutSeconds

EventBridge 等待一次 API 调用需要多长时间，从 1 到 30 秒不等。默认值为 30。这必须是文字整数；这里不接受 JSonata 表达式。

中的交付角色RoleArn需要对您调用的 API 执行 IAM 操作dynamodb:PutItem，例如和sqs:SendMessage对死信队列执行 IAM 操作。有关该角色的信任策略及其余权限，请参阅自定义事件总线的访问控制。

批处理和 $ events 数组

EventBridge 每批调用一次 API，而不是每个事件调用一次。BatchConfiguration设置批次：MaxBatchSize从 1 到 500，MaxBatchWindowInSeconds从 0 到 300。当批次达到相应大小或窗口期满时（以先到者为准）即关闭。

在 Jsonata 中Input，$events是批处理：其中的事件数组。批量大小为 1 时，$events.Data.orderId生成一个事件的值。对于较大的批次，可以显式地对数组进行寻址$join，例如使用 $map and，或者表达式会生成 API 需要字符串但传送失败的数组。

设置MaxBatchSize为 1 和 MaxBatchWindowInSeconds 0 可为每个事件调用一次 API。只要Input是固定的 JSON，就执行此操作，因为批处理中每个事件的固定请求都是相同的，并且批处理会生成一个调用。

示例：每个事件一个 DynamoDB 项目

以下订阅者为发布的每个事件向 DynamoDB 表写入一个项目PutRawEvents，从事件字段中获取分区键。orderId交付角色需要摆在桌面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包含操作的必填字段，对于 JsoNataInput，还要检查表达式是否解析。它不会检查请求中命名的资源是否存在，也不会检查交付角色是否可以调用该操作。这些失败发生在交付时，每次交付失败都会在订阅者下重试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。