使用 JSonata 转换事件

要更改目标接收的内容，请设置TransformerCreateSubscriber或UpdateSubscriber。Transformer.TypeRAW，默认情况下，仅提供已发布的数据；WITH_METADATA提供数据及其元数据；并JSONATA提供表达式的结果，例如{% { "orderId": $events.Data.orderId, "priority": $events.Data.priority } %}。目标为自定义事件总线-Classic 的订阅者仅支持RAW。通用目标不使用Transformer；它使用相同的表达式来塑造自己的请求。UniversalTargetParameters.Input

变压器类型	使用场景	目标有效载荷
RAW	目标需要已发布的事件数据	已发布的数据，未更改。默认值。
WITH_METADATA	目标需要数据及其元数据	带有Data、Metadata和的 JSON 信封 SystemMetadata
JSONATA	目标需要选定的值或新形状	每个事件一个 JSonata 表达式的结果

$events 包含什么

WITH_METADATAJSONATA、，并且每个目标参数表达式都读取相同的输入对象，Jsonata 表达式将其视为相同的输入对象。$events它有三个部分。

{
    "Data": { "orderId": "12345", "priority": "high" },
    "Metadata": { "tenant": "acme" },
    "SystemMetadata": {
        "ContentType": "application/json",
        "aws:EventId": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "aws:IngestionTime": "2026-09-23T18:00:00Z",
        "aws:DeliveryType": "LIVE"
    }
}

• Data是已发布的数据，并保留其 JSON 类型：对象、数组、字符串、数字、布尔值或空值。因为PutRawEvents它是条目的Data值，因此订单标识符位于$events.Data.orderId。因为PutEvents它是整个 EventBridge 信封，带有version、id、detail-type、source、account、time、regionresourcesdetail、和，因此相同的标识符位于处$events.Data.detail.orderId。application/octet-stream因为它是一个 Base64 字符串；请参阅转换二进制数据。

• Metadata是制作人设置的字符串到字符串的映射。PutRawEventsPutEvents不获取任何元数据，因此对于其事件，地图是空的。

• SystemMetadata保存 EventBridge 分配的字段。每个值都是一个字符串。 EventBridge省略没有值的可选字段，省略的字段的计算结果与undefined在 JsoNata 中一样；only 始终存在。aws:DeliveryTypeContentType保留已发布的值，因此 EventBridge解码为 JSON 的 Avro 和 Protobuf 数据仍然显示application/avro或显示application/protobuf在这里，并且会显示一个事件。PutEvents application/eventbridge+json有关每个字段，请参阅SystemMetadata 字段。

引用包含冒号的字段名称，如所示$events.SystemMetadata."aws:EventId"。

使用 JsoNata 构建目标有效载荷

设置Transformer.Type为，JSONATA然后在其中添加一个完整的表达式，用{%和%}括起来JsonataConfiguration.Expression。对于数据为的PutRawEvents条目{"orderId": "12345", "priority": "high", "items": [...]}，以下转换器仅提供两个命名字段。

{
    "Transformer": {
        "Type": "JSONATA",
        "JsonataConfiguration": {
            "Expression": "{% {\"orderId\": $events.Data.orderId, \"priority\": $events.Data.priority} %}"
        }
    }
}

目标接收{"orderId": "12345", "priority": "high"}。 EventBridge 在批处理之前，为每个事件计算一次表达式。结果的类型决定了目标接收的内容。

表达结果	目标有效载荷
字符串	不带 JSON 引号的字符串
对象或数组	序列化的 JSON 对象或数组。null嵌套在里面的 A 仍然是 JSON null。
数字或布尔值	序列化的 JSON 值
null 或 undefined	转换失败；请参阅 限制和失败

转换二进制数据

如果SystemMetadata.ContentType是application/octet-stream，则 EventBridge存储已发布的字节而不对其进行解析，并将它们作为 Base64 字符串向表达式公开。$events.Data的字hello节以$events.Data = "aGVsbG8="。 EventBridge 即使解码后的字节是 JSON 文本，也不会将该字符串解析为 JSON，因此在解释ContentType之前进行检查Data，并且$base64decode($events.Data)仅在原始字节为文本时使用。

{% {
    "contentType": $events.SystemMetadata.ContentType,
    "base64Data": $events.Data
} %}

转换器类型决定字节如何到达目标。RAW只能转发原始字节数组。

变压器类型	目标会得到什么
RAW	原始字节，用于 Kinesis、Firehose、API Gateway 和自定义事件总线目标。Base64 文本，适用于亚马逊 SQS 和亚马逊 SNS 目标。包含 Base64 文本的 JSON 字符串，适用于 Lambda、Step Functions、Custom Event Bus-Classic 和 API 目标目标；批处理 Lambda 或 Step Functions 调用会接收由这些字符串组成的数组。
WITH_METADATA	信封为 UTF-8 JSON，包含 Data Base64 文本
JSONATA	表达式结果为 UTF-8 文本或 JSON；该表达式读取 Base64 文本

无法设置变压器ContentType。当目标是另一个自定义事件总线时， EventBridge 复制已发布的值，唯一的不同是 Avro 和 Protobuf 数据以 JSON 形式交付，因此以 JSON 形式到达。application/json

在目标参数中使用 JSonata

中的InvokeConfiguration目标参数（例如SqsParameters.MessageGroupId）包含一个字面值或一个包含在和中的完整 JSONata 表达式。{% %} EventBridge 不计算嵌入在较长字符串中的表达式。目标参数表达式读取原始输入对象，而不是Transformer生成的有效载荷。以下 Amazon SQS 参数取自每个事件的 FIFO 值。

{
    "InvokeConfiguration": {
        "TargetArn": "arn:aws:sqs:us-east-1:111122223333:orders.fifo",
        "RoleArn": "arn:aws:iam::111122223333:role/SubscriberTargetRole",
        "SqsParameters": {
            "MessageGroupId": "{% $events.Data.customerId %}",
            "MessageDeduplicationId": "{% $events.SystemMetadata.\"aws:EventId\" %}"
        }
    }
}

$events成效取决于参数。 EventBridge 解析每个事件的参数会看到一个输入对象。它每次目标调用解析一次的参数会看到一个输入对象数组，批处理中每个事件一个，所以第一个事件是。$events[0].Data

参数	$events持有
SqsParameters、SnsParametersKinesisParameters、HttpParameters、和 EventBusV2Parameters.Metadata	每个事件一个输入对象
LambdaParameters、StepFunctionsParameters 和 EventBusV2Parameters.DeduplicationConfiguration	每次调用的输入对象数组
UniversalTargetParameters.Input	每次调用的输入对象数组

目标参数表达式必须返回字符串，除非该字段定义了另一种类型；UniversalTargetParameters.Input可以返回构成 API 请求的任何 JSON 值。在映射值参数中，键和字符串值都可以是表达式：SqsParameters.MessageAttributes.name.StringValue、、SqsParameters.MessageSystemAttributes.name.StringValueSnsParameters.MessageAttributes.name.StringValueHttpParameters.QueryStringParameters.key、和。EventBusV2Parameters.Metadata.keyAmazon SQS 或 Amazon SNS 消息属性的值是一个 EventBridge从不计算的字面值 Base64，因此以字节的形式"BinaryValue": "AQID"到达目标0x01 0x02 0x03；用于表达式。BinaryValue StringValue

对于 API 网关目标，每个HttpParameters.HeaderParameters密钥都必须是文字；API 目标目标还允许在标头密钥中使用表达式。 EventBridge 拒绝会覆盖请求签名的标头:AuthorizationHost、以及任何以开头的标头。X-Amz订阅者参数在一个分辨率内的每次$now()和$millis()调用都会返回相同的时间戳。

标准 JSonata 之外的函数

除了标准的 JSonata 库外，还有六个函数可用。

函数	结果
$hash(input, algorithm)	小写十六进制摘要。algorithm区分大小写：MD5SHA-1、、SHA-256SHA-384、或 SHA-512
$uuid()	版本 4 的 UUID
$parse(jsonString)	解析后的 JSON；如果字符串不是有效的 JSON 则出错
$partition(array, chunkSize)	数组拆分成了块
$range(start, end, delta)	数值范围；所有三个参数都是必填的，结果上限为 10,000,000 个元素
$random(seed)	[0, 1) 中的一个数字；同一个种子给出相同的数字

该$eval功能不可用。

限制和失败

Transformer表达式和每个目标参数表达式最多可为 8,192 个字符；通用目标的Input表达式最多可为 262,144 个字符。 EventBridge 在创建或更新订阅者时检查语法，并使用InvalidInputException拒绝无效表达式。在交付时，表达式可以运行一秒钟，使用堆栈深度为 100，并分配 10 MiB。

抛出、超过这些限制，null或者导致该事件传送undefined失败的表达式。 EventBridge 在订阅者下重试RetryPolicy，然后将事件发送到失败目的地（如果已配置）。该EventTransformationFailures指标对每次失败进行计数，EVENT_TRANSFORMATION_FAILURE日志记录带有错误，死信记录为。errorCode INPUT_TRANSFORMATION_FAILURE请参阅自定义事件总线的可观察性：指标、日志和 CloudTrail和重试策略和死信队列。