API 目标的连接创建 API 目标 API 目标的服务相关角色发往 API 目标的请求中包含的标头 API 目标错误代码调用速率如何影响事件交付

API 目的地

Amazon EventBridge API 目标是您可以作为规则目标调用的 HTTP 终端节点，类似于您调用Amazon服务或资源作为目标的方式。使用 API 目标，您可以使用 API 调用在Amazon服务、集成软件即服务 (SaaS) 应用程序和外部应用程序之间路由事件。Amazon当您将 API 目标指定为规则的目标时，为与规则中指定的事件模式匹配的任何事件 EventBridge 调用 HTTP 终端节点，然后随请求一起传送事件信息。使用 EventBridge，您可以使用除 CONNECT 和 TRACE 之外的任何 HTTP 方法进行请求。最常用的 HTTP 方法是 PUT 和 POST。您还可以使用输入转换器根据特定 HTTP 端点参数的参数自定义事件。有关更多信息，请参阅亚马逊 EventBridge 输入转换：

重要

EventBridge 对 API 目标端点的请求的最大客户端执行超时时间必须为 5 秒。如果目标终端节点的响应时间超过 5 秒， EventBridge 则请求超时。 EventBridge 重试超时请求的重试次数不得超过重试策略上配置的最大值。默认情况下，最大值为 24 小时和 185 次。在达到最大重试次数后，如果有死信队列，则将事件发送到死信队列。否则，该事件将被丢弃。

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

本主题内容：

API 目标的连接
创建 API 目标
API 目标的服务相关角色
发往 API 目标的请求中包含的标头
API 目标错误代码
调用速率如何影响事件交付
API 目标合作伙伴

API 目标的连接

创建 API 目标时，您可以指定要用于该目标的连接。连接指定了 API 目标端节点的授权类型和参数。您可以从账户中选择现有连接，也可以在创建 API 目标时创建连接。 EventBridge 支持基本、OAuth 和 API 密钥授权。

对于 Basic 和 API 密钥授权，为您 EventBridge 填充所需的授权标头。对于 OAuth 授权， EventBridge 还可以将您的客户端 ID 和密钥交换为访问令牌，然后对其进行安全管理。创建连接时，还可以包括端点授权所需的标头、正文和查询参数。如果终端节点的授权相同，则可以对多个 API 目标使用相同的连接。

当返回 401 或 407 响应时，会刷新 OAUTH 令牌。

当您创建连接并添加授权参数时， EventBridge 会在中创建密钥Amazon Secrets Manager。存储 Secrets Manager 密钥的成本包含在使用 API 目标的费用中。要详细了解在 API 目标AWS::Events::ApiDestination中使用密钥的最佳实践，请参阅CloudFormation 用户指南中的。

注意

要成功创建或更新连接，您必须使用有权使用 Secrets Manager 的帐户。所需的权限包含在AmazonEventBridgeFullAccess 策略。向在您的账户中创建的用于连接的服务关联角色授予相同的权限。

创建连接

Amazon使用具有管理权限的帐户登录 EventBridge 并打开EventBridge控制台。
在左侧导航窗格中，选择 API 目的地。
向下滚动到 API 目标表，然后选择 “连接” 选项卡。
选择 Create connection (创建连接)。
在创建连接页面上，输入连接的连接名称。
输入连接的描述。
对于授权类型，选择用于授权连接到为使用此连接的 API 目标指定的 HTTP 端点的授权类型。请执行下列操作之一：
- 选择 Basic（用户名/密码），然后输入用于对 HTTP 端点进行授权的用户名和密码。
- 选择 OAuth 客户端证书，然后输入用于对端点进行授权的授权端点、HTTP 方法、客户端 ID 和客户端密钥。
  
  在 OAuth Http 参数下，添加任何其他要包含的用于授权端点的参数。从下拉列表中选择一个参数，然后输入键和值。要包括其他参数，请选择添加参数。
  
  在 “调用 Http 参数” 下，添加要包含在授权请求中的任何其他参数。要添加参数，请从下拉列表中选择一个参数，然后输入键和值。要包括其他参数，请选择添加参数。
- 选择 API 密钥，然后输入用于 API 密钥授权的 API 密钥名称和关联值。
  
  在 “调用 Http 参数” 下，添加要包含在授权请求中的任何其他参数。要添加参数，请从下拉列表中选择一个参数，然后输入键和值。要包括其他参数，请选择添加参数。
选择创建。

要编辑连接，请执行以下操作：

打开 API 目标页面，然后选择 “连接”。
在连接表中，选择要编辑的连接。
在连接详细信息页面上，选择编辑。
更新连接的值，然后选择 “更新”。

取消连接授权

取消对连接的授权时，它会删除所有授权参数。删除授权参数会将密钥从连接中删除，因此您无需创建新连接即可重复使用该密钥。

注意

您必须更新使用已取消授权的连接的任何 API 目标才能使用不同的连接成功向 API 目标终端节点发送请求。

取消对连接的授权

在连接表中，选择连接。
在连接详细信息页面上，选择取消授权。
在取消授权连接中？ 对话框中，输入连接的名称，然后选择取消授权。

在过程完成之前，连接的状态会更改为取消授权。然后，状态更改为已取消授权。现在，您可以编辑连接以添加新的授权参数。

创建 API 目标

每个 API 目的地都需要连接。连接指定了用于 API 目标端节点的授权类型和凭证。您可以选择现有连接，或在创建 API 目标的同时创建连接。

创建 API 目标

Amazon使用具有管理权限的帐户登录 EventBridge 并打开EventBridge控制台。
在左侧导航窗格中，选择 API 目的地。
向下滚动到 API 目标表，然后选择创建 API 目标。
在创建 API 目标页面上，输入 API 目标的名称。您可以使用最多 64 个大写化或小写化字母、数字、点 (.)、短划线 (-) 或下划线 (_) 字符。

名称必须是当前区域中您账户的唯一名称。
输入 API 目标的描述。
输入 API 目标的 API 目标终端节点 API 目标终端节点。API 目标端点是事件的 HTTP 调用端点目标。您在用于此 API 目标的连接中包含的授权信息用于针对此终端节点进行授权。URL 必须使用 HTTPS。
输入用于连接到 API 目标端点的 HTTP 方法。
（可选）在 “每秒调用速率限制” 字段中，输入每秒发送到 API 目标端节点的调用的最大次数。

您设置的速率限制可能会影响事件的 EventBridge 传送方式。有关更多信息，请参阅调用速率如何影响事件交付：
对于 “连接”，执行以下操作之一：
- 选择 “使用现有连接”，然后选择要用于此 API 目标的连接。
- 选择 “创建新连接”，然后输入要创建的连接的详细信息。有关更多信息，请参阅连接。
选择创建。

创建 API 目标后，可以选择它作为规则的目标。要使用 API 目标作为目标，您必须提供具有正确权限的 IAM 角色。有关更多信息，请参阅使用 IAM 角色 EventBridge 访问目标所需的权限

API 目标的服务相关角色

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

以下政策即为 AmazonEventBridgeApiDestinationsServiceRole政策。


{
    "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 文档中的使用服务相关角色。

发往 API 目标的请求中包含的标头

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

标题密钥	标头值
用户代理	亚马逊/EventBridge/ApiDestinations
Content-Type	应用程序/json；charset=utf-8
范围	bytes=0-1048575
Accept-Encoding	gzip、deflate
连接	close
内容长度	表示发送到接收方的实体主体的大小（以字节为单位）的实体标头。
主机	一个请求标头，用于指定发送请求的服务器的主机和端口号。

API 目标错误代码

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

重试与错误代码 429 和 5xx 相关的事件。
不会重试与错误代码 1xx、2xx、3xx 和 4xx（不包括 429）相关的事件。

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

调用速率如何影响事件交付

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

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

配置目标

API 目标合作伙伴