API 目标 - Amazon EventBridge
API 目的地的连接创建 API 目标API 目标的服务相关角色API 目标的请求中包含的标头API 目标错误代码调用率如何影响事件交付
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅中国的 Amazon Web Services 服务入门。

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

API 目标

亚马逊EventBridge API 目标是你可以调用的 HTTP 端点作为目标的规则，类似于你调用Amazon服务或资源作为目标。使用 API 目标，你可以路由事件之间Amazon服务、集成软件即服务 (SaaS) 应用程序和您的应用程序Amazon通过使用 REST API 调用。在将 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 目标时创建连接。EventBridge支持基本、OAuth 和 API 密钥授权。

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

创建连接并添加授权参数时，EventBridge在中创建密钥Amazon Secrets Manager. 存储秘密 Secrets Manager 钥的费用包含在使用 API 目标的费用中。要了解有关将密钥用于 API 目标的最佳实践的更多信息，请参阅AWS::Events::ApiDestination中的CloudFormation用户指南.

注意

要成功创建或更新连接，您必须使用有权使用 Secrets Manager 的帐户。所需的权限包含在AmazonEventBridgeFullAccess 政策. 同样的权限也被授予服务相关角色这是在你的帐户中为连接创建的。

创建连接

  1. 登录到Amazon使用有权管理的账户EventBridge然后打开EventBridge控制台.

  2. 在左侧导航窗格中，选择API 目标.

  3. 向下滚动到API 目标表，然后选择连接选项卡。

  4. 选择 Create connection (创建连接)。

  5. 在存储库的创建连接页面中，输入连接名称对于连接。

  6. 输入说明对于连接。

  7. 适用于授权类型中，选择用于授权与为使用此连接的 API 目标指定的 HTTP 终端节点的连接的授权类型。请执行下列操作之一：

    • 选择基本（用户名/密码），然后输入用户名和密码用于授权 HTTP 终端节点。

    • 选择OAuth 客户端凭证，然后输入授权端点、HTTP method (HTTP 方法)、客户端 ID, 和客户端密钥用于授权终端节点。

      根据OAuth HTTP 参数中，添加要包括的任何其他参数，以便授权终端节点授权。选择参数从下拉列表中，输入密钥和值. 要包括附加参数，请选择添加参数.

      根据调用 Http 参数中，添加要包含在授权请求中的任何其他参数。要添加参数，请选择参数从下拉列表中，输入密钥和值. 要包括附加参数，请选择添加参数.

    • 选择API 密钥，然后输入API 密钥名称和关联值用于 API 密钥授权。

      根据调用 Http 参数中，添加要包含在授权请求中的任何其他参数。要添加参数，请选择参数从下拉列表中，输入密钥和值. 要包括附加参数，请选择添加参数.

  8. 请选择创建。

编辑连接

  1. 打开API 目标页面，然后选择连接.

  2. 在连接表中，选择要编辑的连接。

  3. 在存储库的连接细节页面上，选择编辑.

  4. 更新连接的值，然后选择更新.

取消对连接的授权

取消连接授权时，它会删除所有授权参数。删除授权参数将从连接中删除密钥，因此您可以在不需要创建新连接的情况下重复使用它。

注意

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

取消连接授权

  1. 在连接表中，选择连接。

  2. 在存储库的连接细节页面上，选择取消授权.

  3. 在取消连接的授权？对话框中，输入连接的名称，然后选择取消授权.

连接的状态将更改为取消授权直到该过程完成。然后，状态更改为取消授权. 现在，您可以编辑连接以添加新的授权参数。

创建 API 目标

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

创建 API 目标

  1. 登录到Amazon使用有权管理的账户EventBridge然后打开EventBridge控制台.

  2. 在左侧导航窗格中，选择API 目标.

  3. 向下滚动到API 目标表，然后选择创建 API 目标.

  4. 在存储库的创建 API 目标页面中，输入名称对于 API 目标。您最多可以使用 64 个大写或小写字母、数字、点 (.)、短划线 (-) 或下划线 (_) 字符。

    该名称必须是您在当前区域中账户的唯一名称。

  5. 输入说明对于 API 目标。

  6. 输入API 目标终端节点对于 API 目标。这些区域有：API 目标终端节点是事件的 HTTP 调用终端节点目标。您在用于此 API 目标的连接中包含的授权信息用于针对此终端节点进行授权。URL 必须使用 HTTPS。

  7. 输入HTTP method (HTTP 方法)用于连接到API 目标终端节点.

  8. （可选）对于每秒调用速率限制字段中，输入每秒发送到 API 目标终端节点的最大调用次数。

    您设置的费率限制可能会影响如何EventBridge提供活动。有关更多信息，请参阅 调用率如何影响事件交付。

  9. 适用于Connection，请执行以下操作之一：

    • 选择使用现有连接，然后选择用于此 API 目标的连接。

    • 选择创建新连接，然后输入要创建的连接的详细信息。有关更多信息，请参阅 。连接.

  10. 请选择创建。

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

API 目标的服务相关角色

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

以下是策略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 文档中。

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

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

标题键 标头值

用户代理

Amazon/EventBridge/ApiDestinations

Content-Type

应用程序 /json; charset=utf-8

范围

字节 =0-1048575

Accept-Encoding

gzip，放缩

连接

close

内容长度

指示发送给收件人的实体主体的大小（以字节为单位）。

Host

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

API 目标错误代码

何时EventBridge尝试将事件传输到 API 目标，但会出错，EventBridge执行以下操作：

  • 重试与错误代码 429 和 5xx 相关的事件。

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

EventBridgeAPI 目标读取标准的 HTTP 响应标头Retry-After以了解在提出后续请求之前等待多长时间。EventBridge在定义的重试策略和Retry-After标头。如果Retry-After价值是负数的，EventBridge停止为该事件重试配送。

调用率如何影响事件交付

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