API 目标 - Amazon EventBridge
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

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

API 目标

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

API 目标不支持私有目标,例如接口 VPC 端点。有关更多信息,请参阅将 Amazon EventBridge 与接口 VPC 端点配合使用

重要

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

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

创建 API 目标

每个 API 目标都需要一个连接。连接 指定向 API 目标端点授权的授权类型和要使用的凭证。您可以选择现有连接,也可以在创建 API 目标的同时创建连接。有关更多信息,请参阅 HTTP 终端节点目标的连接

使用 EventBridge 控制台创建 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. 输入连接到 API 目标端点使用的 HTTP 方法

  8. (可选)在每秒调用速率限制字段中,输入每秒发送到 API 目标端点的调用次数上限。

    您设置的速率限制可能会影响事件的 EventBridge 交付方式。有关更多信息,请参阅调用率如何影响事件传送

  9. 对于连接,执行以下操作之一:

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

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

  10. 选择 创建

创建规则,向 API 目标发送事件

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

选择 API 目标作为目标,是创建规则的一部分。

使用控制台创建规则,向 API 目标发送事件
  1. 遵循创建对事件作出反应的 Amazon EventBridge 规则过程中的步骤。

  2. 在该选择目标步骤中,当系统提示您选择 API 目标作为目标类型时:

    1. 选择 EventBridge API 目的地

    2. 请执行以下操作之一:

      • 选择使用现有 API 目的地,然后选择现有 API 目的地

      • 选择创建新 API 目标并指定必要的设置来定义新 API 目标。

        有关指定所需设置的更多信息,请参阅创建 API 目标

    3. (可选):要为事件指定标题参数,请在标题参数下选择添加标头参数

      接下来,指定标头参数的键和值。

    4. (可选):要为事件指定查询字符串参数,请在查询字符串参数下选择添加查询字符串参数

      接下来,为查询字符串参数指定键和值。

  3. 按照步骤完成规则的创建。

API 目标的服务相关角色

当您为 API 目标创建连接时,名为 Destinat Amazon ServiceRoleForAmazonEventBridgeApii ons 的服务相关角色会添加到您的账户。 EventBridge 使用服务相关角色在 Secrets Manager 中创建和存储密钥。要向服务相关角色授予必要的权限,请将AmazonEventBridgeApiDestinationsServiceRole策略策略 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)

  • 亚太地区(大阪)

  • 亚太地区(首尔)

  • 亚太地区(新加坡)

  • 亚太地区(悉尼)

  • 亚太地区(东京)

  • 加拿大(中部)

  • 欧洲地区(法兰克福)

  • 欧洲地区(爱尔兰)

  • 欧洲地区(伦敦)

  • 欧洲地区(米兰)

  • 欧洲地区(巴黎)

  • Europe (Stockholm)

  • 欧洲地区(米兰)

  • South America(São Paulo)

  • 中国(宁夏)

  • 中国(北京)

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

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

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

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

标头键 标头值

用户代理

亚马逊//EventBridgeApiDestinations

Content-Type

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

application/json; charset=utf-8

Range

bytes=0-1048575

Accept-Encoding

gzip,deflate

Connection

close

内容长度

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

Host

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

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

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

  • 用户代理

  • Range

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

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

  • A-IM

  • Accept-Charset

  • Accept-Datetime

  • Accept-Encoding

  • Cache-Control

  • Connection

  • Content-Encoding

  • 内容长度

  • Content-MD5

  • Date

  • 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会执行以下操作:

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

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

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

调用率如何影响事件传送

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