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

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

API 目的地作为亚马逊的目标 EventBridge

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

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

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

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

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

注意

EventBridge 当使用私有时，API 目标目前仅支持带有公开信任证书的 HTTPS 终端节点的公共域名 APIs。API 目的地不支持双向 TLS (mTLS)。

重要

EventBridge 向 API 目标端点发出的请求的最大客户端执行超时时间必须为 5 秒。如果目标端点的响应时间超过 5 秒， EventBridge 则请求超时。 EventBridge 重试会将请求超时到重试策略上配置的最大值。

  • 对于活动总线，默认情况下，最大值为 24 小时和 185 次。

  • 对于管道，重试取决于管道源类型及其配置。 EventBridge 将重试，直到事件从源端到期，或者已达到配置的最大事件时限或重试尝试次数。

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

以下视频演示了 API 目标的用法：

API 目标的服务相关角色

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

以下策略是 AmazonEventBridgeApiDestinationsServiceRolePolicy。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:CreateSecret",
                "secretsmanager:UpdateSecret",
                "secretsmanager:DescribeSecret",
                "secretsmanager:DeleteSecret",
                "secretsmanager:GetSecretValue",
                "secretsmanager:PutSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
        }
    ]
}

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

区域可用性

以下 Amazon 区域支持AmazonEventBridgeApiDestinationsServiceRolePolicy服务相关角色：

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

  • 美国东部（俄亥俄州）

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

  • 美国西部（俄勒冈州）

  • 非洲（开普敦）

  • 亚太地区（香港）

  • Asia Pacific (Mumbai)

  • 亚太地区（大阪）

  • 亚太地区（首尔）

  • 亚太地区（新加坡）

  • 亚太地区（悉尼）

  • 亚太地区（东京）

  • 加拿大（中部）

  • 欧洲地区（法兰克福）

  • 欧洲地区（爱尔兰）

  • 欧洲地区（伦敦）

  • 欧洲地区（米兰）

  • 欧洲地区（巴黎）

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

  • 南美洲（圣保罗）

  • 中国（宁夏）

  • 中国（北京）

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

以下部分详细介绍如何 EventBridge 处理发往 API 目标的请求中的 HTTP 标头。

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

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

标头键 标头值

用户代理

Amazon/EventBridge/ApiDestinations

Content-Type

如果未指定自定义 “内容类型” 值，则 EventBridge 包括以下默认值作为 “内容类型”：

application/json; charset=utf-8

Range

bytes=0-1048575

Accept-Encoding

gzip,deflate

Connection

关闭

内容长度

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

Host

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

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

EventBridge 不允许您覆盖以下标题：

  • 用户代理

  • Range

从 API 目标请求中 EventBridge 移除标头

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

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • Connection

  • Content-Encoding

  • 内容长度

  • 内容-MD5

  • 日期

  • Expect

  • Forwarded

  • From

  • Host

  • HTTP2-设置

  • 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、407409429、和5xx关联的事件。

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

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

调用率如何影响事件传送

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