amazon-eventbridge-event-bus

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Building with the new EventBridge custom event buses

使用新的 EventBridge 自定义事件总线进行构建

Overview

概述

The new EventBridge custom event bus routes events and retains them. You publish with one of two APIs, and subscribers filter, optionally transform, and deliver each matching event to one target.
Read chapters 5 and 6 before writing any filter, transformer, or target parameter. The two publish APIs deliver different payload shapes, and an expression written for one silently matches nothing against the other.
Publish metrics are on by default, so you can always tell whether events reached a bus. Subscriber logs are off by default, so turn them on before you debug a delivery rather than after (chapter 18).
Works best with the AWS MCP server, which is recommended for running the CLI calls in this skill: it executes them in a sandboxed environment with audit logging. All guidance also works with standard AWS CLI access.
新的 EventBridge 自定义事件总线负责路由事件并保留它们。你可以使用两个 API 之一进行发布,订阅者会对事件进行过滤、可选地转换,并将每个匹配的事件投递到一个目标。
**在编写任何过滤器、转换器或目标参数之前,请先阅读第 5 章和第 6 章。**两个发布 API 生成的 payload 形状不同,为其中一个 API 编写的表达式在另一个 API 上会静默地什么都不匹配。
发布指标默认开启,因此你始终可以判断事件是否到达总线。订阅者日志默认关闭,因此请在调试投递之前(而不是之后)开启它们(见第 18 章)。
最佳搭配 AWS MCP server,建议用它运行本技能中的 CLI 调用:它会在带审计日志的沙盒环境中执行调用。所有指南也适用于标准 AWS CLI 访问。

Conventions

约定

The key words MUST, MUST NOT, SHOULD, and MAY in this skill are to be interpreted as described in RFC 2119. They appear only in decision procedures, where following the wrong course either breaks the configuration or loses events silently. MUST marks an absolute requirement, SHOULD a strong recommendation you may have a specific reason to set aside, and MAY a genuine option.
Everything else is ordinary description. A sentence stating how the service behaves carries no keyword, because it is a fact rather than an instruction to you.
本技能中的关键词 MUST、MUST NOT、SHOULD 和 MAY 应按照 RFC 2119 中的描述进行解释。它们只出现在决策过程中,在决策过程中选错方向要么会破坏配置,要么会静默丢失事件。MUST 表示绝对要求,SHOULD 表示强烈建议(你可能有特定理由不遵守),MAY 表示真正的可选事项。
其余内容皆为普通描述。描述服务行为的句子不携带关键词,因为这是事实而非对你发出的指令。

When not to use this skill

何时不应使用本技能

This skill is only about the new custom event buses, the service you reach with the
eventbridgev2
CLI and SDK clients. It does not cover:
  • Classic EventBridge, meaning the
    events
    API with rules, targets, archives, and event patterns on
    AWS::Events::Rule
    . The two services share the
    events:
    IAM namespace and some vocabulary, which is exactly why they are easy to confuse. If you are writing a rule, you are not on a new bus. Chapter 3 maps the concepts across if you are migrating.
  • EventBridge Pipes, Scheduler, and Schemas (the classic schema registry and its discovery feature). Different APIs.
  • Configuring the Firehose service itself, such as buffering hints or record transformation. A Firehose delivery stream is a valid subscriber target; chapter 9 covers that side of it.
本技能只针对新的自定义事件总线,即通过
eventbridgev2
CLI 和 SDK 客户端访问的服务。它不涵盖:
  • 经典 EventBridge,即使用规则、目标、归档和事件模式的
    events
    API,对应
    AWS::Events::Rule
    。两种服务共享
    events:
    IAM 命名空间和一些词汇,这正是它们容易混淆的原因。如果你在编写规则,那么你不在新的总线上。第 3 章在迁移时给出了概念映射。
  • EventBridge Pipes、Scheduler 和 Schemas(经典 schema 注册表及其发现功能)。不同 API。
  • 配置 Firehose 服务本身,如缓冲提示或记录转换。Firehose 投递流是有效的订阅者目标;第 9 章涵盖这一侧。

Trigger examples

触发示例

  1. "Write a filter so this subscriber only gets orders over $500."
  2. "My producer says PUBLISHED but nothing shows up in the queue. What do I check?"
  3. "Should I use PutEvents or PutRawEvents for Protobuf payloads?"
  4. "Set up a subscriber that reprocesses everything from the last two days."
  5. "Write a JSONata expression that pulls the customer id out of the event into a DynamoDB putItem."
  1. "写一个过滤器,让这个订阅者只接收超过 500 美元的订单。"
  2. "我的生产者显示 PUBLISHED,但队列中没有出现任何内容。我该检查什么?"
  3. "对于 Protobuf payload,我应该使用 PutEvents 还是 PutRawEvents?"
  4. "设置一个订阅者,重新处理过去两天的一切。"
  5. "编写一个 JSONata 表达式,将事件中的客户 id 提取出来,放入 DynamoDB putItem。"

Guardrail — where this skill's own files live (MCP vs local install)

护栏 —— 本技能自身文件的位置(MCP 与本地安装)

This skill can be loaded two ways, and they resolve the skill's own bundled files from different places. Determine how the skill was loaded before reading a reference:
  • Loaded through the AWS MCP
    retrieve_skill
    tool:
    The skill is not installed on the local filesystem. You MUST fetch each reference via
    retrieve_skill
    with the
    file
    parameter (e.g.
    file="references/setup-walkthroughs.md"
    ). Do NOT
    file_read
    these paths locally — they do not exist on disk.
  • Installed locally (e.g.
    .kiro/skills/amazon-eventbridge-event-bus/
    or
    ~/.claude/skills/amazon-eventbridge-event-bus/
    ): Read files from the local skill directory using relative paths.
This distinction applies only to the skill's own packaged files. User data and session artifacts are always read from and written to the user's working directory. Never fetch or write customer data through
retrieve_skill
.
本技能可以通过两种方式加载,它们从不同位置解析技能自带的文件。在读取参考文件之前,先确定技能是如何加载的:
  • 通过 AWS MCP
    retrieve_skill
    工具加载:
    技能未安装在本地文件系统。你必须通过
    retrieve_skill
    并带
    file
    参数获取每个参考文件(例如
    file="references/setup-walkthroughs.md"
    )。不要用
    file_read
    读取这些本地路径——它们不存在于磁盘上。
  • 本地安装(例如
    .kiro/skills/amazon-eventbridge-event-bus/
    或
    ~/.claude/skills/amazon-eventbridge-event-bus/
    ):使用相对路径从本地技能目录读取文件。
此区别仅适用于技能自带的打包文件。用户数据和会话工件始终在用户的工作目录中读写。永远不要通过
retrieve_skill
获取或写入客户数据。

Reference files

参考文件

The chapters below carry the decisions and the failure modes; the detail lives in these files. Load a file when the task matches its row, and do not load them all by default.
FileWhen to load
setup-walkthroughs.mdstanding up a working bus end to end, in one account or shared across accounts with AWS RAM, including prerequisites and teardown
code-samples.mdwriting an individual CLI or SDK call (Python, Java, TypeScript): create a bus and subscriber, publish with either API, binary payloads, replay, cross-account grants, waiters, per-entry results, throttling backoff
filters-and-expressions.mdwriting any filter pattern, JSONata expression, or target parameter that reads the event; both delivered envelopes in full
target-configuration.mdconfiguring any subscriber target, especially a universal target
target-contract.mdwriting an actual
CreateSubscriber
call: required fields, a working example per target type, literal versus JSONata, the delivery error taxonomy
migrating-from-classic.mdmigrating from classic EventBridge, planning the migration sequence, or classic habits producing wrong new-bus config
event-sources.mdputting AWS service events or partner events on a bus with an event source, or forwarded events not arriving or not matching a filter
provisioning-and-state.mdcreating or updating a bus, or a resource stuck in an unexpected state
delivery-troubleshooting.mdan event published but never arrived, or building a test rig that counts deliveries correctly
authorization.mdwriting an IAM policy or bus resource policy, cross-account access checks, or anything that forwards events into a bus
replay-and-recovery.mdreading history rather than new events, pausing or resuming, or a replay that looks broken
observability.mdsetting up metrics, alarms, or the vended-log delivery; reading delivery logs; observing across accounts
schema-registries.mdpublishing Avro, Protobuf, or anything that is not JSON; the accepted content types; running alongside Kafka
cloudevents.mdpublishing or consuming CloudEvents, or filtering on CloudEvents attributes
security-and-sharing.mdencrypting a bus, sharing it cross-account, or tagging
cost-and-quotas.mdbilling mechanics, who pays what across accounts, shaping events for cost, or handling throttling
infrastructure-as-code.mdwriting a CloudFormation template, splitting stacks across accounts, or private connectivity

下面各章包含决策和故障模式;细节位于这些文件中。当任务与某行匹配时加载对应文件,不要默认全部加载。
文件何时加载
setup-walkthroughs.md端到端搭建一个可用总线,在单个账户中或通过 AWS RAM 跨账户共享,包括前置条件和拆除
code-samples.md编写单个 CLI 或 SDK 调用(Python、Java、TypeScript):创建总线和订阅者、使用任一 API 发布、二进制 payload、回放、跨账户授权、waiter、逐条结果、限流退避
filters-and-expressions.md编写任何过滤器模式、JSONata 表达式或读取事件的目标参数;两种完整投递信封
target-configuration.md配置任何订阅者目标,尤其是通用目标
target-contract.md编写实际的
CreateSubscriber
调用:必填字段、每种目标类型的工作示例、字面量与 JSONata、投递错误分类
migrating-from-classic.md从经典 EventBridge 迁移、规划迁移顺序,或经典习惯导致新总线配置错误
event-sources.md通过事件源将 AWS 服务事件或合作伙伴事件放到总线上,或转发的事件未到达或未匹配过滤器
provisioning-and-state.md创建或更新总线,或资源卡在意外状态
delivery-troubleshooting.md事件已发布但从未到达,或构建能正确计算投递次数的测试装置
authorization.md编写 IAM 策略或总线资源策略、跨账户访问检查,或任何将事件转发到总线的内容
replay-and-recovery.md读取历史而非新事件、暂停或恢复,或看起来异常的回放
observability.md设置指标、告警或 vended-log 投递;读取投递日志;跨账户观察
schema-registries.md发布 Avro、Protobuf 或任何非 JSON 内容;可接受的内容类型;与 Kafka 并行运行
cloudevents.md发布或消费 CloudEvents,或基于 CloudEvents 属性进行过滤
security-and-sharing.md加密总线、跨账户共享或打标签
cost-and-quotas.md计费机制、跨账户谁支付什么、为成本而整形事件,或处理限流
infrastructure-as-code.md编写 CloudFormation 模板、跨账户拆分 stack,或私有连接

1. The three resources

1. 三个资源

Event bus. The thing you publish to. It routes events and retains them.
Subscriber. A statement of which events you want and where to send them, in one resource. It watches its bus, keeps the events matching its filter, optionally transforms each one, and delivers it to exactly one target. To send one event to several targets, create several subscribers on the same bus.
Event source. A managed feed into a bus, either AWS service events or a partner/SaaS source.
Names and identifiers:
  • A bus ARN and a subscriber ARN both end in a service-generated id after the name:
    arn:aws:events:us-east-1:111122223333:event-busv2/my-bus/exampleid0123456789abcdef
    . Store the full ARN, not the name, because the name alone does not identify the resource and re-creating a deleted bus with the same name yields a different id.
  • Event source names are unique per account, not per bus.
  • Three names identify this service and they do not match. The CLI command and every SDK client are
    eventbridgev2
    , as in
    aws eventbridgev2 create-event-bus
    . IAM actions and ARNs are
    events
    , shared with classic EventBridge, as in
    events:PutEvents
    and
    arn:aws:events:...:event-busv2/...
    . The endpoint host is
    eventsv2.{region}.amazonaws.com
    . See chapter 14.
事件总线。 你发布事件的目标。它路由并保留事件。
订阅者。 在一个资源中声明你想要哪些事件以及发送到哪里。它监视其总线,保留与其过滤器匹配的事件,可选地转换每个事件,并恰好投递到一个目标。要将一个事件发送到多个目标,请在同一个总线上创建多个订阅者。
事件源。 通往总线的受管数据源,可以是 AWS 服务事件,也可以是合作伙伴/SaaS 源。
名称和标识符:
  • 总线 ARN 和订阅者 ARN 均以服务生成的 id 结尾,位于名称之后:
    arn:aws:events:us-east-1:111122223333:event-busv2/my-bus/exampleid0123456789abcdef
    。请存储完整 ARN 而非名称,因为仅凭名称无法标识资源,并且以相同名称重新创建已删除的总线会得到不同的 id。
  • 事件源名称在账户内唯一,而非在每个总线内唯一。
  • 三个名称标识此服务,但它们并不一致。 CLI 命令和所有 SDK 客户端是
    eventbridgev2
    ,如
    aws eventbridgev2 create-event-bus
    。IAM 操作和 ARN 是
    events
    ,与经典 EventBridge 共享,如
    events:PutEvents
    和
    arn:aws:events:...:event-busv2/...
    。端点主机是
    eventsv2.{region}.amazonaws.com
    。见第 14 章。

2. A router with a durable log behind it

2. 带有持久日志的路由器

The bus routes each event to matching subscribers, and it also retains events for a configured period, set per bus with
StorageConfiguration.RetentionPeriodInDays
(1 to 365 days). Retention is what makes four other features possible: starting positions, pausing and resuming, replay, and a subscriber created today reading events published yesterday. The retention window is clamped at the bus's creation time, so on a young bus even a recent past timestamp can fall outside it.
总线将每个事件路由到匹配的订阅者,同时按配置的期限保留事件,期限在每个总线上通过
StorageConfiguration.RetentionPeriodInDays
设置(1 到 365 天)。保留正是另外四个功能成为可能的基础:起始位置、暂停和恢复、回放,以及今天创建的订阅者读取昨天发布的事件。保留窗口在总线创建时被钳制,所以在年轻的总线上,即使是最近的过去时间戳也可能落在窗口之外。

3. Coming from classic EventBridge

3. 从经典 EventBridge 迁移而来

A classic rule plus its target becomes one subscriber on the new bus. Four new-bus concepts have no classic analogue: retention on the bus itself, a subscriber starting position, pause and resume with a backlog, and two publish APIs with different payload models. That last changes how you write filters, so a classic event pattern ported unchanged works only for
PutEvents
. The concept mapping, the habits that carry over incorrectly, and a step-by-step migration sequence are in migrating-from-classic.md.
一个经典规则及其目标在新的总线上变成一个订阅者。四个新总线概念在经典中没有对等物:总线本身的保留期、订阅者起始位置、带积压的暂停和恢复,以及两个具有不同 payload 模型的发布 API。最后一点改变了你编写过滤器的方式,因此原封不动移植的经典事件模式只对
PutEvents
有效。概念映射、错误沿用的习惯以及逐步迁移顺序见 migrating-from-classic.md。

4. AWS service and partner event sources

4. AWS 服务和合作伙伴事件源

An event source is a managed feed onto your bus. You create one naming a destination bus and one origin, and the service stands up the forwarding on the classic EventBridge side for you. There is no role and no delivery code: the managed path uses the service's own identity.
Configuration
is discriminated and exactly one variant MUST be set:
VariantOriginRequired member
AwsServiceEventsConfiguration
one AWS service, as
aws.s3
AwsService
PartnerEventsConfiguration
a classic partner event source
PartnerEventSourceArn
Both take an optional
Pattern
, which narrows what forwards and is evaluated on the classic side against the classic envelope. Your pattern MUST NOT carry a
source
key or a top-level
account
or
region
, because the service sets those itself to pin the forward to your account and origin.
A forwarded event arrives as the whole classic envelope.
Data
holds it,
ContentType
is
application/eventbridge+json
, your content is at
$events.Data.detail
, and the source and detail-type are in
SystemMetadata
as
aws:Source
and
aws:DetailType
. So a classic rule's
source
filter does not transfer: the equivalent is a
SYSTEM_METADATA
filter,
{"aws:Source":["aws.s3"]}
.
Only that
SystemMetadata
pair proves an AWS service or partner produced the event.
No publish call can write either key. A raw payload can imitate the envelope exactly, so a
DATA
filter on the payload's
source
matches a forgery as readily as the real thing. You SHOULD filter on
aws:Source
whenever provenance matters
, and MUST match its value rather than its presence, because a direct
PutEvents
sets the key too, from its own never-
aws.
-prefixed
Source
.
EventBusArn
is immutable. Recovery splits by failure: from
CREATE_FAILED
or
UPDATE_FAILED
,
UpdateEventSource
converges the classic side back to your record, while from
DELETE_FAILED
the only recovery is another delete.
A bus owner's control is at create time.
CreateEventSource
is authorized against the destination bus with an
events:source
condition key, and
RevokeResource
is how an owner stops a feed that already exists (chapter 22). Prerequisites, encryption, dead-lettering, and what appears in your classic account are in event-sources.md.
事件源 是通往你总线的受管数据源。你创建一个事件源,指定一个目标总线和一个来源,服务会在经典 EventBridge 一侧为你搭建转发。没有角色,也没有投递代码:受管路径使用服务自身的身份。
Configuration
是判别联合,且必须恰好设置一个变体:
变体来源必需成员
AwsServiceEventsConfiguration
一个 AWS 服务,如
aws.s3
AwsService
PartnerEventsConfiguration
一个经典合作伙伴事件源
PartnerEventSourceArn
两者都接受可选的
Pattern
,用于缩小转发范围,并在经典侧针对经典信封进行求值。你的模式不能携带
source
键,也不能携带顶层
account
或
region
,因为服务会自行设置这些以将转发固定到你的账户和来源。
转发的事件以完整经典信封的形式到达。
Data
保存事件,
ContentType
为
application/eventbridge+json
,你的内容位于
$events.Data.detail
,source 和 detail-type 在
SystemMetadata
中,分别为
aws:Source
和
aws:DetailType
。因此经典规则的
source
过滤器不能直接迁移:等价物是
SYSTEM_METADATA
过滤器
{"aws:Source":["aws.s3"]}
。
只有这对
SystemMetadata
才能证明事件由 AWS 服务或合作伙伴产生。
任何发布调用都无法写入这两个键。原始 payload 可以精确模仿经典信封,因此针对 payload 的
source
的
DATA
过滤器,会同样容易地匹配伪造事件和真实事件。只要来源归属重要,你 SHOULD 就使用
aws:Source
过滤
,并且 MUST 匹配其值而不只是其存在,因为直接
PutEvents
也会设置该键,来自自身从不带
aws.
前缀的
Source
。
EventBusArn
不可变。恢复按失败类型区分:从
CREATE_FAILED
或
UPDATE_FAILED
,
UpdateEventSource
会将经典侧收敛回你的记录;而
DELETE_FAILED
的唯一恢复方式是再次删除。
总线所有者的控制发生在创建时。
CreateEventSource
通过
events:source
条件键针对目标总线授权,
RevokeResource
是所有者停止已存在数据源的方式(第 22 章)。前置条件、加密、死信以及你经典账户中出现的内容见 event-sources.md。

5. Choosing a publish API

5. 选择发布 API

The choice fixes the payload shape, and the payload shape determines every filter, transformer, and target parameter you go on to write.
PutEvents
PutRawEvents
Payload field
Detail
, a JSON string
Data
, a base64 blob
Payload must be JSONYesNo, any format
Required per entry
Source
,
DetailType
Data
,
SystemMetadata
ContentType
Not accepted; the service stamps
application/eventbridge+json
Required, inside each entry's
SystemMetadata
Classic-style fields
Resources
,
Time
available
Not present
Your own metadataNo
Metadata
, up to 100 keys
Ordering and dedup inputs
SystemMetadata.EventGroupId
,
SystemMetadata.DeduplicationId
Same two fields
Use
PutEvents
for JSON events where you want the classic-shaped envelope. Use
PutRawEvents
for binary or non-JSON payloads, your own metadata keys, or a payload delivered exactly as sent.
Both return one result entry per request entry in the same order, so you correlate by index. Each carries either a
SuccessCode
or an
ErrorCode
and
ErrorMessage
.
SuccessCode
is
PUBLISHED
or
DEDUPLICATED
, and
DEDUPLICATED
is a success, not an error.
Code that treats every success as a new event makes deduplication look like delivery.
Publishing Avro or Protobuf requires a schema registry named on each publish request, not on the bus; a registry configured in the wrong place leaves your events undecoded.
application/octet-stream
needs no registry, because the service does not decode those bytes at all (schema-registries.md).
选择决定了 payload 的形状,而 payload 形状又决定了你之后编写的所有过滤器、转换器和目标参数。
PutEvents
PutRawEvents
Payload 字段
Detail
,一个 JSON 字符串
Data
,一个 base64 blob
Payload 必须是 JSON是否,任意格式
每个条目的必填项
Source
,
DetailType
Data
,
SystemMetadata
ContentType
不接受;服务盖章
application/eventbridge+json
必需,位于每个条目的
SystemMetadata
内
经典风格字段
Resources
,
Time
可用
不存在
你自己的元数据无
Metadata
,最多 100 个键
排序和去重输入
SystemMetadata.EventGroupId
,
SystemMetadata.DeduplicationId
同样的两个字段
对于希望使用经典结构信封的 JSON 事件,使用
PutEvents
。对于二进制或非 JSON payload、你自己的元数据键,或需要按发送时原样投递的 payload,使用
PutRawEvents
。
两者都按相同顺序为每个请求条目返回一个结果条目,因此你可以按索引关联。每个条目携带
SuccessCode
或
ErrorCode
加
ErrorMessage
。
SuccessCode
为
PUBLISHED
或
DEDUPLICATED
,
DEDUPLICATED
是成功,而不是错误。
将每个成功都当作新事件处理的代码,会把去重误判为投递问题。
发布 Avro 或 Protobuf 需要在每个发布请求上指定 schema 注册表,而不是在总线上;配置在错误位置的注册表会让你的事件无法解码。
application/octet-stream
不需要注册表,因为服务完全不解码这些字节(见 schema-registries.md)。

6. Addressing: where every field lives

6. 寻址:每个字段所在位置

Filters, transformers, and target parameters share one addressing model, and it is not the same for the two publish APIs. Every event is delivered under three top-level names:
Data
(the payload),
Metadata
(your own keys,
PutRawEvents
only), and
SystemMetadata
(service-assigned and ordering fields). A raw-published payload sits directly in
Data
; a
PutEvents
payload sits inside the classic envelope, one level down under
detail
. So the same field is
$events.Data.m
for one API and
$events.Data.detail.m
for the other, and the wrong form does not error: it resolves to nothing, the filter matches nothing, and the transformer emits nothing. If you publish through both APIs onto one bus, write expressions that work for both, or give each traffic type its own subscribers; no addressing form spans both. Both envelopes in full, with every
SystemMetadata
field, are in filters-and-expressions.md.
过滤器、转换器和目标参数共享一个寻址模型,而且它在两个发布 API 下并不相同。 每个事件在三个顶层名称下投递:
Data
(payload)、
Metadata
(你自己的键,仅
PutRawEvents
)和
SystemMetadata
(服务分配和排序字段)。原始发布的 payload 直接位于
Data
中;
PutEvents
的 payload 位于经典信封内,在
detail
下一层。因此同一字段在一个 API 中是
$events.Data.m
,在另一个 API 中是
$events.Data.detail.m
,而错误形式不会报错:它解析为空,过滤器什么都不匹配,转换器什么都不输出。如果你通过两个 API 发布到同一条总线,请编写对两者都有效的表达式,或让每种流量类型使用各自的订阅者;没有任何寻址形式能同时覆盖两者。完整的两种信封,包括所有
SystemMetadata
字段,见 filters-and-expressions.md。

7. Filtering

7. 过滤

A subscriber's
FilterConfiguration
holds a list of
Filters
, and an event must match every filter in the list to be delivered: the filters are ANDed, not ORed. Each filter has a
Pattern
and a
Scope
(
DATA
,
METADATA
, or
SYSTEM_METADATA
), one filter per scope. A
DATA
pattern is written against the chapter 6 shape, so one pattern cannot serve both publish APIs; each is correct for exactly one API and silently matches nothing for the other.
FilterConfiguration
is optional on create, and a subscriber without one receives every event on the bus. A filter that matches nothing is indistinguishable from a broken subscriber, so confirm a should-match and a should-not-match case by observing the target.
订阅者的
FilterConfiguration
包含一个
Filters
列表,事件必须匹配列表中的每个过滤器才会被投递:过滤器之间是 AND 关系,而非 OR 关系。每个过滤器有
Pattern
和
Scope
(
DATA
、
METADATA
或
SYSTEM_METADATA
),每个 scope 一个过滤器。
DATA
模式是针对第 6 章的形状编写的,因此一个模式无法同时服务两个发布 API;每个模式只对其中一个 API 正确,对另一个 API 静默匹配不到任何内容。
FilterConfiguration
在创建时可选,没有它的订阅者会接收总线上的所有事件。一个什么都不匹配的过滤器与故障订阅者无法区分,因此请通过观察目标来确认应匹配和不应匹配的情况。

8. Transformation

8. 转换

A subscriber's
Transformer
has three types:
RAW
(the default) delivers the payload alone,
WITH_METADATA
delivers the three-part envelope, and
JSONATA
delivers the result of an expression. A JSONata expression is wrapped in
{% %}
delimiters and sees the event as
$events
, addressed exactly as in chapter 6. Most scalar target parameters also accept an expression in the same form. Some members refuse one and MUST be literals: an API Gateway header name, a message attribute's
BinaryValue
, and
InvocationType
. An expression is only syntax-checked at create, so its result is a delivery-time fact. A
JSONATA
transformer whose expression throws, or evaluates to nothing, is a customer-fault delivery failure, so you SHOULD test it.
订阅者的
Transformer
有三种类型:
RAW
(默认)只投递 payload,
WITH_METADATA
投递三部分信封,
JSONATA
投递表达式的结果。JSONata 表达式用
{% %}
定界符包裹,并将事件视为
$events
,寻址方式与第 6 章完全一致。大多数标量目标参数也接受同样形式的表达式。某些成员不接受表达式,MUST 使用字面量:API Gateway 的头名称、消息属性的
BinaryValue
和
InvocationType
。表达式在创建时只做语法检查,因此其结果在投递时才成为事实。
JSONATA
转换器的表达式抛出异常或求值为空,属于客户侧投递失败,因此你 SHOULD 对其进行测试。

9. Targets and their parameter blocks

9. 目标及其参数块

InvokeConfiguration
carries the
TargetArn
, the
RoleArn
, and at most one parameter block, matching the target. A universal target MUST carry its block; every typed block may be omitted. A classic bus and a Firehose delivery stream are both valid targets that take no block at all.
The service resolves the target type from the ARN and checks the invariants it owns before storing anything: that the block matches the target, that the ARN's region, partition and account are its own, and that every expression parses. It does not mirror the target API's own parameter grammars, value ranges, identifier limits, or which members that API requires — those stay with the target, so a request the target will reject is accepted at create and fails at delivery.
  1. You MUST supply the parameter block a universal target requires. A typed block may be omitted:
    KinesisParameters: {}
    is stored, and Kinesis reports the missing
    PartitionKey
    when it is called.
  2. You MUST NOT put a constant in a per-message field, because a constant deduplication id makes the target discard everything after the first message. Neither form is checked against the target's range, requiredness or FIFO applicability, so a bad or missing value is a delivery failure.
  3. You SHOULD check the target service's own rules. Existence, reachability, authorization, size after enveloping, and its API's required fields are enforced by the target, at delivery.
  4. You SHOULD confirm at the target, because a
    PUBLISHED
    response is not delivery, and neither is an HTTP 200 from a batch API, which can carry individually failed entries.
  5. You MUST attach a dead-letter queue and turn on logs before you test, and MUST grant the delivery role
    sqs:SendMessage
    on that queue
    , because a failure otherwise leaves no signal anywhere.
Each rule's failure mode, the exact rejection messages, and the per-target blocks are in target-configuration.md. Before writing the call itself, load target-contract.md for the required-field lists, one working example per target type, and the delivery error taxonomy.
InvokeConfiguration
携带
TargetArn
、
RoleArn
,以及至多一个与目标匹配的参数块。通用目标 MUST 携带其参数块;所有类型化块都可以省略。经典总线和 Firehose 投递流都是有效的目标,它们完全不需要参数块。
服务会在存储任何内容之前,从 ARN 解析目标类型并检查其自身拥有的不变量:参数块与目标匹配、ARN 的区域、分区和账户属于服务自身,以及每个表达式都能解析。它不会镜像目标 API 自身的参数语法、取值范围、标识符限制或该 API 要求哪些成员——这些由目标负责,因此一个会被目标拒绝的请求,在创建时被接受,在投递时才失败。
  1. 你必须提供通用目标所需的参数块。 类型化块可以省略:
    KinesisParameters: {}
    会被存储,Kinesis 在被调用时会报告缺少
    PartitionKey
    。
  2. 你不能在逐消息字段中放置常量,因为常量去重 id 会让目标丢弃第一条消息之后的所有内容。这两种形式都不会对照目标的范围、必填性或 FIFO 适用性进行检查,因此错误或缺失的值都会导致投递失败。
  3. 你应该检查目标服务自身的规则。 存在性、可达性、授权、加信封后的大小以及其 API 的必填字段,都由目标在投递时强制执行。
  4. 你应该在目标处确认,因为
    PUBLISHED
    响应不等于投递成功,批处理 API 返回的 HTTP 200 也不等于成功,它可能携带单独失败的条目。
  5. 你必须在测试前附加死信队列并开启日志,并且必须授予投递角色对该队列的
    sqs:SendMessage
    权限
    ,否则故障不会在任何地方留下信号。
每条规则的故障模式、精确的拒绝消息和每个目标的参数块见 target-configuration.md。在编写调用本身之前,请加载 target-contract.md 查看必填字段列表、每种目标类型的一个工作示例以及投递错误分类。

10. Universal targets

10. 通用目标

A universal target invokes any supported AWS API directly, with no intermediate function. The target ARN has a fixed shape:
arn:{partition}:events:::aws-sdk:{service}:{apiAction}
Four things to get right, each of which fails at create time with a message that names the problem:
apiAction
is camelCase with a lowercase first letter (
putItem
);
service
is the SDK service id, which is not always the obvious word (Step Functions is
sfn
);
UniversalTargetParameters.Input
is required and holds the API request as JSON or a JSONata expression producing it; and
BatchConfiguration
is required. The service's validation text abbreviates universal target as "USI target"; the two mean the same thing.
通用目标直接调用任何受支持的 AWS API,不需要中间函数。目标 ARN 具有固定结构:
arn:{partition}:events:::aws-sdk:{service}:{apiAction}
有四件事需要做对,每件都会在创建时失败并给出指明问题的消息:
apiAction
是首字母小写的驼峰形式(
putItem
);
service
是 SDK 服务 id,并不总是显而易见的词(Step Functions 是
sfn
);
UniversalTargetParameters.Input
为必填项,以 JSON 或生成它的 JSONata 表达式形式保存 API 请求;
BatchConfiguration
为必填项。服务的校验文本将 universal target 缩写为 "USI target";两者含义相同。

11. Ordering and deduplication

11. 排序和去重

Ordering is a subscriber property.
Type
is
UNORDERED
(no guarantee) or
FIFO
(ordered within an event group), and events are grouped by
SystemMetadata.EventGroupId
at publish time. A FIFO target enforces its own length and character limits on the group id, and an undeliverable event holds up the later events in its own group while other groups on the same subscriber keep flowing, so keep group ids bounded and do not derive them from unbounded input.
Deduplication happens at publish time, two ways.
DeduplicationConfiguration.DeduplicationType: CONTENT_BASED
on the request hashes the event content, and
CONTENT_BASED
is the only
DeduplicationType
value. To deduplicate on your own key instead, omit
DeduplicationConfiguration
and set
SystemMetadata.DeduplicationId
on each entry. A suppressed duplicate returns
SuccessCode: DEDUPLICATED
either way.
Keep the two ideas separate. Bus-level deduplication decides whether an event is accepted. A FIFO target's own deduplication id, set in the target parameter block, decides whether that target accepts the delivery. Different fields at different layers, and the second is a per-message value (chapter 9, rule 2).
排序是订阅者的属性。
Type
为
UNORDERED
(无保证)或
FIFO
(在事件组内有序),事件在发布时按
SystemMetadata.EventGroupId
分组。FIFO 目标对组 id 强制执行自己的长度和字符限制,并且一个无法投递的事件会阻塞其所在组中的后续事件,而同一订阅者上的其他组继续流动,因此请保持组 id 有界,不要从无界输入推导它们。
去重发生在发布时,有两种方式。请求上的
DeduplicationConfiguration.DeduplicationType: CONTENT_BASED
对事件内容进行哈希,
CONTENT_BASED
是唯一的
DeduplicationType
值。若想改用你自己的键去重,请省略
DeduplicationConfiguration
,并在每个条目上设置
SystemMetadata.DeduplicationId
。无论哪种方式,被抑制的重复项都会返回
SuccessCode: DEDUPLICATED
。
请区分这两个概念。总线级去重决定事件是否被接受。FIFO 目标自身的去重 id(在目标参数块中设置)决定该目标是否接受投递。不同层使用不同字段,其中第二个是逐消息值(第 9 章规则 2)。

12. Retries and dead-lettering

12. 重试和死信

RetryPolicy
has three members:
MemberRangeDefault
MaxRetryAttempts
0-1855
MaxEventAgeInSeconds
60-86400300
RetryStrategy
ALL
ALL
Delivery stops at whichever limit is reached first, and a failing delivery is retried until then. So a conclusion that "nothing arrived" is only safe after the
MaxEventAgeInSeconds
window has elapsed.
OnFailureConfiguration.Arn
names an SQS queue for dead-lettering, and SQS is the only supported destination. An event source refuses a FIFO queue there, with the single message
OnFailureConfiguration.Arn must name a standard SQS queue: FIFO queues are not supported as EventSource dead-letter queues
; a subscriber accepts one, so the two resources differ on this point. Two further limits to plan around: a dead-letter record identifies failed events by id and timestamp and does not carry the payload, so replaying it needs the event still inside retention; and the dead-letter queue must be writable by the delivery role, or the failure has nowhere to go and the events disappear with no signal.
RetryPolicy
有三个成员:
成员范围默认值
MaxRetryAttempts
0-1855
MaxEventAgeInSeconds
60-86400300
RetryStrategy
ALL
ALL
投递在任一限制先达到时停止,失败的投递会一直重试到那时。因此,只有过了
MaxEventAgeInSeconds
窗口之后,才能安全地得出“什么都没到达”的结论。
OnFailureConfiguration.Arn
指定一个用于死信的 SQS 队列,SQS 是唯一受支持的目标。事件源会拒绝该处的 FIFO 队列,并给出单一消息
OnFailureConfiguration.Arn must name a standard SQS queue: FIFO queues are not supported as EventSource dead-letter queues
;订阅者接受 FIFO 队列,因此两个资源在这一点上不同。还有两个需要规划的限制:死信记录通过 id 和时间戳标识失败事件,不携带 payload,因此要回放它,事件必须仍在保留期内;死信队列必须可由投递角色写入,否则失败无处可去,事件会在没有任何信号的情况下消失。

13. Delivery permissions

13. 投递权限

InvokeConfiguration.RoleArn
is the role the service assumes to invoke your target. It MUST belong to the calling account, its trust policy MUST allow the
events.amazonaws.com
service principal, and that policy SHOULD condition on
aws:SourceAccount
and
aws:SourceArn
. It MUST carry the action the target requires (
sqs:SendMessage
,
sns:Publish
,
lambda:InvokeFunction
,
kinesis:PutRecords
,
states:StartExecution
, or whatever your universal target calls), and
sqs:SendMessage
on your dead-letter queue
, or deliveries fail, no failure record is written, and nothing is observable.
CreateSubscriber
also enforces
iam:PassRole
on that role, so a role you cannot pass fails with
AccessDeniedException
before target validation runs. The list understates four: Kinesis delivery calls
PutRecords
, Firehose
PutRecordBatch
, API Gateway needs
execute-api:Invoke
, an API destination
events:InvokeApiDestination
.
The target ARN is checked at create for shape, type, region, partition and account, but not for existence or reachability: a well-formed ARN naming nothing is stored and fails at delivery.
InvokeConfiguration.RoleArn
是服务调用你的目标时所扮演的角色。它 MUST 属于调用账户,其信任策略 MUST 允许
events.amazonaws.com
服务主体,并且该策略 SHOULD 对
aws:SourceAccount
和
aws:SourceArn
加条件。它 MUST 携带目标所需的操作(
sqs:SendMessage
、
sns:Publish
、
lambda:InvokeFunction
、
kinesis:PutRecords
、
states:StartExecution
,或你的通用目标调用的任何操作),以及对你死信队列的
sqs:SendMessage
,否则投递失败、不写入失败记录,并且一切不可观察。
CreateSubscriber
还对该角色强制执行
iam:PassRole
,因此你无法传递的角色会在目标校验运行之前以
AccessDeniedException
失败。上面的列表低估了四个:Kinesis 投递调用
PutRecords
,Firehose 调用
PutRecordBatch
,API Gateway 需要
execute-api:Invoke
,API 目的地需要
events:InvokeApiDestination
。
目标 ARN 在创建时会检查结构、类型、区域、分区和账户,但不检查存在性或可达性:一个格式正确但指向不存在的目标的 ARN 会被存储,并在投递时失败。

14. Authorization: what your caller needs

14. 授权:你的调用者需要什么

Chapter 13 covers the role EventBridge assumes to invoke your target. This chapter covers what your caller needs to reach the API.
Every action name is
events:
.
The CLI command and the SDK clients are named
eventbridgev2
, and the endpoint host is
eventsv2
, but the IAM namespace is
events
, shared with classic EventBridge. You MUST NOT write
eventbridgev2:
or
eventsv2:
in an IAM policy
, because neither names an action that exists, and both fail closed: the policy is accepted and grants nothing. A policy written from the command you just ran, granting
eventbridgev2:PutEvents
, is the usual way this happens. The name-by-name map is in authorization.md.
Publishing is authorized against the bus ARN, per entry, with no partial authorization: if one entry fails a condition check the whole request is denied, so a batch is only as authorized as its least authorized entry.
Creating a subscriber or an event source is authorized against the bus, which makes the bus the cross-account grant point: a bus owner decides there whether another account may attach anything.
Forwarding into a bus under a role you supply is authorized at ingestion, per event: a genuine AWS or partner event needs
events:PutEvents
, and anything you originated needs
events:PutRawEvents
. So a forwarder carrying both kinds MUST be granted both actions, because granting one silently denies half the stream. The condition keys, the per-create checks, and revocation semantics are in authorization.md.
第 13 章介绍 EventBridge 调用你的目标时所扮演的角色。本章介绍你的调用者访问 API 需要什么。
每个操作名称都是
events:
。
CLI 命令和 SDK 客户端命名为
eventbridgev2
,端点主机为
eventsv2
,但 IAM 命名空间是
events
,与经典 EventBridge 共享。你不能在 IAM 策略中写
eventbridgev2:
或
eventsv2:
,因为这两个都不是存在的操作名称,并且都会失败关闭:策略被接受但不授予任何权限。从你刚运行的命令生成的策略授予
eventbridgev2:PutEvents
,这是最常见的出错方式。逐名称映射见 authorization.md。
发布针对总线 ARN 按条目授权,没有部分授权:如果某个条目未通过条件检查,整个请求都会被拒绝,因此一个批次的授权程度取决于其中授权最少的条目。
创建订阅者或事件源是针对总线授权的,这使得总线成为跨账户授权点:总线所有者在那里决定另一个账户是否可以附加任何内容。
在你提供的角色下转发到总线,是在摄取时按事件授权的:真实的 AWS 或合作伙伴事件需要
events:PutEvents
,而你发起的任何内容需要
events:PutRawEvents
。因此,同时携带两种事件的转发者必须被授予两个操作,因为只授予一个会静默拒绝一半流。条件键、逐创建检查和撤销语义见 authorization.md。

15. Provisioning and resource state

15. 预置和资源状态

Creating a bus is asynchronous:
CreateEventBus
returns with
State: CREATING
, and the bus becomes usable later. Use the waiter rather than a hand-rolled poll, because it fails fast on the failure states and surfaces
StateReason
instead of spinning to a timeout:
aws eventbridgev2 wait event-bus-active  --event-bus-arn "$BUS_ARN"
A bus has seven states, and the asymmetry that matters is between the two failure states:
UPDATE_FAILED
is recoverable in place, and
CREATE_FAILED
is not.
A failed create permits only delete, so that bus must be deleted and recreated. Delete subscribers and event sources before the bus; a bus that still has either rejects
DeleteEventBus
with
ResourceInUseException
, and the message names which kind is blocking. Revoked subscribers and event sources do not block the delete.
Creates are idempotent through
ClientToken
.
CreateEventBus
,
CreateSubscriber
, and
CreateEventSource
each accept one, and a retry carrying the same token returns the original result rather than creating a second resource. An SDK generates a fresh token per call when you omit the field, so a retry your own code issues builds a new request, gets a new token, and creates a second resource. So you MUST supply your own
ClientToken
whenever a retry can cross a process, a queue, or a workflow step.
The mismatch error and the naming collision are in provisioning-and-state.md.
创建总线是异步的:
CreateEventBus
返回时
State: CREATING
,总线稍后才可用。请使用 waiter 而不是手写轮询,因为它会在失败状态上快速失败并显示
StateReason
,而不是一直轮询到超时:
aws eventbridgev2 wait event-bus-active  --event-bus-arn "$BUS_ARN"
总线有七种状态,其中关键的不对称性在于两个失败状态:
UPDATE_FAILED
可以在原地恢复,而
CREATE_FAILED
不能。
创建失败只允许删除,因此该总线必须删除后重建。在删除总线之前先删除订阅者和事件源;仍然带有任一资源的总线会以
ResourceInUseException
拒绝
DeleteEventBus
,消息会指明是哪种资源在阻塞。已被撤销的订阅者和事件源不会阻塞删除。
创建操作通过
ClientToken
实现幂等。
CreateEventBus
、
CreateSubscriber
和
CreateEventSource
都接受一个 token,携带相同 token 的重试会返回原始结果,而不会创建第二个资源。当你省略该字段时,SDK 会在每次调用时生成一个新 token,因此你自己代码发起的重试会构建新请求、获得新 token,并创建第二个资源。因此,只要重试可能跨越进程、队列或工作流步骤,你 MUST 就提供自己的
ClientToken
。
不匹配错误和命名冲突见 provisioning-and-state.md。

16. Updating safely

16. 安全更新

One rule governs every update API, and getting it wrong silently discards configuration you did not intend to change:
An omitted top-level member means unchanged. A supplied configuration block replaces that whole block.
So an update that supplies
Configuration
or
FilterConfiguration
or
LogConfiguration
in order to change one field inside it clears every other field in that block. An event source updated with its
Pattern
omitted comes back with no pattern at all, widening its filter to everything, with no warning. So you MUST read the resource, modify the whole block, write the whole block back, and then read it back again, because reading it back is the only way to confirm what was stored.
一条规则支配所有更新 API,搞错它会静默丢弃你本不想更改的配置:
省略的顶层成员表示不变。提供的配置块会替换整个块。
因此,为更改其中某一字段而提供
Configuration
、
FilterConfiguration
或
LogConfiguration
的更新,会清除该块中的其他所有字段。 省略
Pattern
更新事件源后,它会以完全没有模式的状态返回,将其过滤器扩大到所有内容,且没有任何警告。因此你 MUST 读取资源、修改整个块、写回整个块,然后再次读取,因为读回是确认实际存储内容的唯一方式。

17. Pausing, resuming, and replay

17. 暂停、恢复和回放

There is no separate replay API. Replay is a subscriber's starting position, evaluated against the bus's retained events, so anything still inside retention can be reread.
  • StartingPosition
    at create time is
    LATEST
    (only events published after the subscriber exists) or
    POINT_IN_TIME
    (from a point in retained history).
  • Pausing is
    State: STOPPED
    on
    UpdateSubscriber
    . The backlog accrues, bounded by retention, and
    ResumePosition
    decides whether the backlog is delivered or skipped on resume.
  • Replayed events are marked.
    SystemMetadata."aws:DeliveryType"
    reads
    REPLAY
    instead of
    LIVE
    , so a consumer can make replay idempotent.
  • A replay has a startup delay, then runs at live speed, so allow for the delay before concluding a replay is broken.
没有独立的回放 API。回放是订阅者的起始位置,针对总线保留的事件进行求值,因此仍在保留期内的任何内容都可以重新读取。
  • StartingPosition
    在创建时为
    LATEST
    (仅限订阅者创建之后发布的事件)或
    POINT_IN_TIME
    (从保留历史中的某个时间点开始)。
  • 暂停是
    UpdateSubscriber
    上的
    State: STOPPED
    。积压会累积,受保留期限制,
    ResumePosition
    决定恢复时积压是被投递还是被跳过。
  • 回放事件带有标记。
    SystemMetadata."aws:DeliveryType"
    读取为
    REPLAY
    而不是
    LIVE
    ,因此消费者可以令回放幂等。
  • 回放有启动延迟,然后以实时速度运行,因此在断定回放异常之前,请把延迟考虑在内。

18. Observability: metrics and logs

18. 可观测性:指标和日志

Two surfaces tell you what the service is doing, and their defaults are opposite.
Publish metrics are on by default, in the
AWS/EventsV2
namespace, on the tuple
{EventBus}
plus
{EventBus, EventSource}
for traffic attributed to an event source and
{EventBus, PublisherAccount}
for ingress bytes.
PublishEventsApproximateCallCount
against
PublishEventsApproximateSuccessCallCount
is the cheapest check that your producer is reaching the bus at all. The outcome metrics count calls, not events, so a call that returned a response counts as a success even when every entry in it was rejected;
PublishEventsEntryCount
against
PublishEventsFailedEntriesCount
is what says whether events landed. The
EventBus
dimension value is not the bus ARN
; querying with the ARN returns no data and looks identical to no traffic.
Subscriber logs are off by default, and they need two things before they exist:
LogConfiguration.Level
raised above
OFF
, and a CloudWatch Logs vended-log delivery wiring the subscriber to a log group. Set both up before debugging a delivery, not after. The delivery setup, the metric list, and the
EVENT_DELIVERY_ATTEMPT
record fields are in observability.md.
两个层面告诉你服务在做什么,它们的默认设置正好相反。
发布指标默认开启,位于
AWS/EventsV2
命名空间,维度元组为
{EventBus}
,外加
{EventBus, EventSource}
(针对归因于事件源的流量)和
{EventBus, PublisherAccount}
(针对入口字节)。
PublishEventsApproximateCallCount
对比
PublishEventsApproximateSuccessCallCount
是判断你的生产者是否到达总线的最廉价检查。结果指标统计的是调用次数,而非事件数,因此即使调用返回的响应中每个条目都被拒绝,该调用也计为成功;
PublishEventsEntryCount
对比
PublishEventsFailedEntriesCount
才能说明事件是否真正落地。
EventBus
维度值不是总线 ARN
;用 ARN 查询不会返回数据,看起来与没有流量完全一样。
订阅者日志默认关闭,它们的存在需要两件事:
LogConfiguration.Level
提升到
OFF
以上,以及 CloudWatch Logs vended-log 投递将订阅者连接到日志组。请在调试投递之前设置好这两项,而不是之后。投递设置、指标列表和
EVENT_DELIVERY_ATTEMPT
记录字段见 observability.md。

19. Verifying delivery

19. 验证投递

A publish response tells you the service accepted the event. It says nothing about delivery. To know an event arrived, look at the target.
A healthy delivery reaches the target quickly, so an event that has not arrived promptly is probably failing rather than in flight. But "nothing arrived" is only sound after the retry window elapses, because until then a failing delivery is still being retried.
Two counting mistakes make a working setup look broken. Reading an SQS queue without deleting the messages re-reads them, so raw counts overstate deliveries. And a shared target accumulates messages from earlier runs, so use a fresh target per experiment or a marker unique to the run.
发布响应告诉你服务接受了事件。它不说明投递情况。要知道事件是否到达,请查看目标。
健康投递会快速到达目标,因此一个没有及时到达的事件很可能是在失败,而不是在途中。 但“什么都没到达”只有在重试窗口过去之后才成立,因为在此之前,失败的投递仍在被重试。
两个计数错误会让正常配置看起来像坏了。读取 SQS 队列而不删除消息会重新读取它们,因此原始计数会高估投递次数。共享目标会累积之前运行的旧消息,因此每次实验使用全新目标,或使用本次运行独有的标记。

20. When it published but never arrived

20. 当它已发布但从未到达

Nearly every delivery problem presents identically: the publish succeeded and the target is empty. You SHOULD work the ordered procedure in delivery-troubleshooting.md; it covers eleven causes ordered by how often each is the answer.
Three shortcuts that do not require opening the file:
  • You SHOULD check
    PublishEventsEntryCount
    first
    (chapter 18). Zero means the problem is upstream of the bus and nothing downstream matters yet.
  • You SHOULD turn on subscriber logs.
    INFO
    with
    IncludePayload: FULL
    shows the per-attempt error and the exact
    target_input
    sent, without waiting for retries to exhaust.
  • To see the event as the service sees it, you MAY add a second subscriber with
    Transformer: { Type: WITH_METADATA }
    and no filter, pointed at a queue you own.
几乎每个投递问题都以相同方式呈现:发布成功,但目标为空。你 SHOULD 按照 delivery-troubleshooting.md 中的有序流程排查;它按每种原因成为答案的频率排序,介绍了十一种原因。
三个不需要打开文件的快捷方式:
  • 你应该首先检查
    PublishEventsEntryCount
    (第 18 章)。为零表示问题在总线上游,下游任何内容都还不重要。
  • 你应该开启订阅者日志。 带
    IncludePayload: FULL
    的
    INFO
    会显示每次尝试的错误和发送的精确
    target_input
    ,无需等待重试耗尽。
  • 要查看服务眼中的事件,你可以 MAY 添加第二个订阅者,使用
    Transformer: { Type: WITH_METADATA }
    且不带过滤器,指向你自己拥有的队列。

21. Errors and client retries

21. 错误和客户端重试

Batch responses are per entry. A publish can return success at the request level with individual entries failed, so check
FailedEntryCount
and every entry, not just the HTTP status.
Some malformed input fails the whole request instead of one entry. Anything caught while deserializing the request rejects the entire batch and takes the valid entries with it. Validate per entry client-side, and keep batches small enough that losing one is cheap.
Retryable errors.
ConcurrentModificationException
and
ThrottlingException
are retryable with backoff.
InvalidInputException
,
AccessDeniedException
,
ResourceNotFoundException
, and
IdempotentParameterMismatchException
are not; fix the request.
Treat a persistent 500 as a client-side wire-type problem first. The usual cause is a value sent as the wrong JSON type, such as a number where a string is expected or an ISO-8601 string where epoch seconds are. An SDK retries a 500 by contract, and retrying cannot fix a malformed request, so check your types before escalating.
批量响应是逐条目的。 发布可能在请求级别返回成功,但其中个别条目失败,因此请检查
FailedEntryCount
和每个条目,而不只是 HTTP 状态。
某些格式错误的输入会使整个请求失败,而不是单个条目。 在反序列化请求过程中捕获到的任何问题都会拒绝整个批次,连有效条目一起拒绝。请在客户端逐条目校验,并保持批次足够小,以让丢失一个条目的代价足够低。
可重试错误。
ConcurrentModificationException
和
ThrottlingException
可通过退避重试。
InvalidInputException
、
AccessDeniedException
、
ResourceNotFoundException
和
IdempotentParameterMismatchException
不可重试;请修复请求。
将持续的 500 错误首先视为客户端线缆类型问题。 常见原因是以错误的 JSON 类型发送值,例如应为字符串却发送数字,或应为 epoch 秒却发送 ISO-8601 字符串。SDK 按约定重试 500 错误,而重试无法修复格式错误的请求,因此在升级前请检查你的类型。

22. Security, encryption, sharing, tagging

22. 安全、加密、共享、标签

  • Encryption is
    EncryptionConfiguration.KmsKeyIdentifier
    on the bus. Your caller needs
    kms:DescribeKey
    on the key at create time, and on a CMK bus every publisher needs
    kms:Decrypt
    on that key too
    , because a caller who cannot read the bus's events back is not allowed to write them. An unusable key policy on the service's side settles the bus at
    CREATE_FAILED
    with
    StateReason: KMS_ACCESS_DENIED
    instead (security-and-sharing.md).
  • To share a bus with another account, use AWS RAM. Resource policies are the fallback for what RAM cannot express, and a hand-written policy is invisible to RAM, so you then own tracking it.
  • Some operations are restricted to the bus owner, including revoking a shared resource, so a permission grant alone is not always sufficient. Revocation is terminal and scoped to the one resource you name, so stopping an account rather than a resource means also denying it
    events:CreateSubscriber
    and
    events:CreateEventSource
    in the bus resource policy (authorization.md).
  • 加密是总线上的
    EncryptionConfiguration.KmsKeyIdentifier
    。你的调用者在创建时需要对该密钥的
    kms:DescribeKey
    权限,在 CMK 总线上每个发布者也需要对该密钥的
    kms:Decrypt
    权限
    ,因为无法读回总线事件的调用者不允许写入它们。服务侧不可用的密钥策略会使总线以
    CREATE_FAILED
    和
    StateReason: KMS_ACCESS_DENIED
    告终(见 security-and-sharing.md)。
  • 要与另一个账户共享总线,请使用 AWS RAM。 资源策略是 RAM 无法表达的情况的备选方案,而手写策略对 RAM 不可见,因此之后你需要自己负责跟踪它。
  • 某些操作仅限于总线所有者,包括撤销共享资源,因此仅授予权限并不总是足够。撤销是终局性的,并且限定在你指定的那一个资源上,因此要阻止一个账户而不是一个资源,意味着还要在总线资源策略中拒绝其
    events:CreateSubscriber
    和
    events:CreateEventSource
    (见 authorization.md)。

23. Cost, quotas, and platform integration

23. 成本、配额和平台集成

Four things that change design decisions. Current prices and quota values are on the EventBridge pricing page and in Service Quotas, not here.
  • Billing rounds up per KB on both ingestion and delivery, so many tiny events cost more than the byte total suggests; batching related facts into one event is cheaper.
  • "Enriched operations" are billed separately: JSONata evaluation, schema deserialization, and
    CONTENT_BASED
    deduplication. So prefer a per-entry
    DeduplicationId
    , with no
    DeduplicationConfiguration
    , when you already have an idempotency key.
  • Publishing is throttled per account across both publish APIs, so a service splitting traffic between them draws from one budget. Subscriber management has its own per-account limit, so
    CreateSubscriber
    and
    DeleteSubscriber
    can be throttled while publishing has headroom. Handle
    ThrottlingException
    with backoff (chapter 21).
  • CloudFormation covers the new buses under
    AWS::EventsV2::
    , with three types. Six subscriber properties are create-only and replacement is delete-then-create, so changing a target ARN in a template can silently drop events published during the gap.
四件会改变设计决策的事情。当前价格和配额值见 EventBridge 定价页面 和 Service Quotas,此处不列出。
  • 计费在摄取和投递两侧都按每 KB 向上取整,因此许多小事件的成本比字节总数所暗示的更高;把相关事实批量放入一个事件更便宜。
  • “增强操作”单独计费:JSONata 求值、schema 反序列化和
    CONTENT_BASED
    去重。因此当你已有幂等键时,优先使用逐条目
    DeduplicationId
    ,而不带
    DeduplicationConfiguration
    。
  • 发布在两个发布 API 之间按账户共享限流,因此在它们之间拆分流量的服务使用同一个预算。订阅者管理有自己的按账户限制,因此
    CreateSubscriber
    和
    DeleteSubscriber
    可能在发布仍有余量时被限流。使用退避处理
    ThrottlingException
    (第 21 章)。
  • CloudFormation 在
    AWS::EventsV2::
    下覆盖新总线
    ,共有三种类型。订阅者的六个属性是仅创建时有效的,替换方式是先删后建,因此在模板中更改目标 ARN 可能会静默丢弃间隙期间发布的事件。