将 API 目标指定为 Amazon EventBridge 中的目标 - Amazon EventBridge
服务相关角色请求中的标头API 目标错误代码调用率和事件传送区域可用性
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

将 API 目标指定为 Amazon EventBridge 中的目标

EventBridge API 目标是可以作为事件总线规则或管道的目标进行调用的 HTTPS 端点，类似于将 Amazon 服务或资源作为目标进行调用的方式。使用 API 目标，您可以借助 API 调用在 Amazon 服务、集成的软件即服务（SaaS）应用程序以及公有或私有应用程序之间路由事件。

当您将 API 目标指定为规则或管道的目标时，EventBridge 会为与该规则或管道中指定的事件模式匹配的任何事件调用 HTTPS 端点，然后随请求一起传送事件信息。借助 EventBridge，您可以使用除 CONNECT 和 TRACE 之外的任何 HTTP 方法来处理请求。最常用的 HTTP 方法是 PUT 和 POST。

您也可以使用输入转换器，将事件自定义为特定 HTTP 端点参数的参数。有关更多信息，请参阅 Amazon EventBridge 输入转换。

API 目标使用带有授权参数的连接将事件发送到 HTTP 端点。

EventBridge API 目标使用连接来定义授权方法、凭证以及网络连接性，以便 EventBridge 在连接到特定 HTTPS 端点时使用。连接同时支持公有和私有 API。有关更多信息，请参阅 连接。

注意

EventBridge API 目标目前仅支持使用私有 API 时，具有公开可信证书的公共域名作为 HTTPS 端点。API 目标不支持双向 TLS（mTLS）。

重要

向 API 目标端点发出 EventBridge 请求的客户端执行超时上限必须为 5 秒。如果目标端点的响应时间超过 5 秒，EventBridge 会将该请求设为超时。EventBridge 会根据重试策略中配置的上限重试超时的请求。

  • 对于事件总线，默认情况下，上限为 24 小时和 185 次。

  • 对于管道，重试次数取决于管道源类型及其配置。EventBridge 将持续重试，直至事件在源端过期，或达到配置的最大事件期限或重试次数上限。

达到重试次数上限后，会将事件发送到死信队列（如有）。否则，该事件将被丢弃。

API 目标的服务相关角色

为 API 目标创建连接时，系统会将服务关联角色 AmazonEventBridgeApiDestinationsServiceRolePolicy 添加到您的账户中。EventBridge 会使用此服务相关角色在 Secrets Manager 中创建并存储密钥。为了向服务相关角色授予必要的权限，EventBridge 为该角色附加了 AmazonEventBridgeApiDestinationsServiceRolePolicy 策略。该策略授予的权限，仅限于角色与连接密钥交互所必需的权限，不包括其他权限。该角色只能与您账户中的连接进行交互，以管理密钥。

有关服务相关角色的更多信息，请参见 IAM 用户指南中的使用服务相关角色。

向 API 目标发送的请求中的标头

下一部分将详细介绍 EventBridge 如何处理向 API 目标发送的请求中的 HTTP 标头。

向 API 目标发送的请求中包含的标头

除了为用于 API 目标的连接定义的授权标头外，EventBridge 在每个请求中还包括以下标头。

标头键 标头值

用户代理

Amazon/EventBridge/ApiDestinations

Content-Type

如果未指定自定义 Content-Type 值，则 EventBridge 会将以下默认值作为 Content-Type：

application/json; charset=utf-8

Range

bytes=0-1048575

Accept-Encoding

gzip,deflate

Connection

关闭

内容长度

表示发送到接收方的实体正文的大小（以字节为单位）的实体标头。

Host

一个请求标头，指定发送请求的服务器的主机和端口号。

向 API 目标发送的请求中无法覆盖的标头

EventBridge 不允许覆盖以下标头：

  • 用户代理

  • Range

EventBridge 在向 API 目标发送的请求中移除的标头

EventBridge 会删除所有 API 目标请求的以下标头：

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • Connection

  • Content-Encoding

  • 内容长度

  • Content-MD5

  • 日期

  • Expect

  • Forwarded

  • From

  • Host

  • HTTP2-Settings

  • If-Match

  • If-Modified-Since

  • If-None-Match

  • If-Range

  • If-Unmodified-Since

  • Max-Forwards

  • Origin

  • Pragma

  • Proxy-Authorization

  • Range

  • Referer

  • TE

  • Trailer

  • Transfer-Encoding

  • 用户代理

  • Upgrade

  • Via

  • Warning

API 目标错误代码

如果 EventBridge 尝试将事件传送到 API 目标时发生错误，EventBridge 会执行以下操作：

  • 重试与错误代码 401、407、409、429、和 5xx 关联的事件。

  • 不重试与错误代码 1xx、2xx、3xx、和 4xx（上述错误代码除外）关联的事件。

EventBridge API 目标会读取标准 HTTP 响应标头 Retry-After，以确定需要等待多长时间再发出后续请求。对于事件总线，EventBridge 会在定义的重试策略和 Retry-After 标头之间选择更保守的值。如果 Retry-After 值为负，EventBridge 将停止重试该事件的传送。

调用率如何影响事件传送

如果将每秒调用速率设置为远低于生成的调用数量的值，则可能无法在 24 小时的重试时间内传送此事件。例如，如果您将调用速率设置为每秒 10 次调用，但每秒会生成数千个事件，则很快就会有超过 24 小时的待传送事件积压。为确保不会丢失任何事件，请设置一个死信队列，将调用失败的事件发送到该队列，以便日后可以处理这些事件。有关更多信息，请参阅 在 EventBridge 中使用死信队列处理未传送的事件。

区域可用性

以下 Amazon 区域支持将 API 目标设置为公共 HTTPS 端点：

  • 美国东部（弗吉尼亚州北部）

  • 美国东部（俄亥俄州）

  • 美国西部（加利福尼亚北部）

  • 美国西部（俄勒冈州）

  • 非洲（开普敦）

  • 亚太地区（香港）

  • 亚太地区（东京）

  • 亚太地区 (首尔)

  • 亚太地区（大阪）

  • 亚太地区（孟买）

  • 亚太地区（海得拉巴）

  • 亚太地区（新加坡）

  • 亚太地区（悉尼）

  • 亚太地区（雅加达）

  • 加拿大（中部）

  • 中国（北京）

  • 中国（宁夏）

  • 欧洲地区（法兰克福）

  • 欧洲（苏黎世）

  • 欧洲地区（斯德哥尔摩）

  • 欧洲地区（米兰）

  • 欧洲（西班牙）

  • 欧洲地区（爱尔兰）

  • 欧洲地区（伦敦）

  • 欧洲地区（巴黎）

  • 中东（阿联酋）

  • 中东（巴林）

  • 南美洲（圣保罗）