本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 JSonata 转换事件 要更改目标接收的内容，请设置`Transformer``CreateSubscriber`或`UpdateSubscriber`。`Transformer.Type``RAW`，默认情况下，仅提供已发布的数据；`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_METADATA``JSONATA`、，并且每个目标参数表达式都读取相同的输入对象，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`、`region``resources``detail`、和，因此相同的标识符位于处`$events.Data.detail.orderId`。`application/octet-stream`因为它是一个 Base64 字符串；请参阅[转换二进制数据](#eb-custom-bus-transform-binary)。 + `Metadata`是制作人设置的字符串到字符串的映射。`PutRawEvents``PutEvents`不获取任何元数据，因此对于其事件，地图是空的。 + `SystemMetadata`保存 EventBridge 分配的字段。每个值都是一个字符串。 EventBridge省略没有值的可选字段，省略的字段的计算结果与`undefined`在 JsoNata 中一样；only 始终存在。`aws:DeliveryType``ContentType`保留已发布的值，因此 EventBridge解码为 JSON 的 Avro 和 Protobuf 数据仍然显示`application/avro`或显示`application/protobuf`在这里，并且会显示一个事件。`PutEvents` `application/eventbridge+json`有关每个字段，请参阅[SystemMetadata 字段](eb-custom-bus-addressing.md#eb-custom-bus-addressing-system)。 引用包含冒号的字段名称，如所示`$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 | 转换失败；请参阅 [限制和失败](#eb-custom-bus-transform-limits) | ## 转换二进制数据 如果`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}}.StringValue``SnsParameters.MessageAttributes.{{name}}.StringValue``HttpParameters.QueryStringParameters.{{key}}`、和。`EventBusV2Parameters.Metadata.{{key}}`Amazon SQS 或 Amazon SNS 消息属性的值是一个 EventBridge从不计算的字面值 Base64，因此以字节的形式`"BinaryValue": "AQID"`到达目标`0x01 0x02 0x03`；用于表达式。`BinaryValue` `StringValue` 对于 API 网关目标，每个`HttpParameters.HeaderParameters`密钥都必须是文字；API 目标目标还允许在标头密钥中使用表达式。 EventBridge 拒绝会覆盖请求签名的标头:`Authorization``Host`、以及任何以开头的标头。`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](eb-custom-bus-observability.md)和[重试策略和死信队列](eb-custom-bus-retry.md)。