本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。
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 目的地
-
Amazon 使用具有管理和 EventBridge 打开EventBridge控制台
权限的账户登录。 -
在左侧导航窗格中,选择 API 目标。
-
向下滚动到 API 目标表,然后选择创建 API 目标。
-
在创建 API 目标页面上,输入 API 目标的名称。您最多可以使用 64 个大写或小写字母、数字、点 (.)、短划线 (-) 或下划线 (_) 字符。
在当前区域中,该名称对于您的账户必须是唯一的。
-
为 API 目标输入描述。
-
为 API 目标输入 API 目标端点。API 目标端点是事件的 HTTP 调用端点目标。用于此 API 目标的连接中包含的授权信息,用于对此端点进行授权。URL 必须使用 HTTPS。
-
输入连接到 API 目标端点使用的 HTTP 方法。
-
(可选)在每秒调用速率限制字段中,输入每秒发送到 API 目标端点的调用次数上限。
您设置的速率限制可能会影响事件的 EventBridge 交付方式。有关更多信息,请参阅调用率如何影响事件传送。
-
对于连接,执行以下操作之一:
-
选择使用现有连接,然后选择要用于此 API 目标的连接。
-
选择创建新连接,然后输入要创建的连接的详细信息。有关更多信息,请参阅连接。
-
-
选择 创建。
创建规则,向 API 目标发送事件
创建 API 目标后,可以将其选为某规则的目标。要使用 API 目标作为目标,您必须提供具有正确权限的 IAM 角色。有关更多信息,请参阅 EventBridge 使用 IAM 角色访问目标所需的权限。
选择 API 目标作为目标,是创建规则的一部分。
使用控制台创建规则,向 API 目标发送事件
遵循创建对事件作出反应的 Amazon EventBridge 规则过程中的步骤。
在该选择目标步骤中,当系统提示您选择 API 目标作为目标类型时:
选择 EventBridge API 目的地。
请执行以下操作之一:
选择使用现有 API 目的地,然后选择现有 API 目的地
选择创建新 API 目标并指定必要的设置来定义新 API 目标。
有关指定所需设置的更多信息,请参阅创建 API 目标。
(可选):要为事件指定标题参数,请在标题参数下选择添加标头参数。
接下来,指定标头参数的键和值。
(可选):要为事件指定查询字符串参数,请在查询字符串参数下选择添加查询字符串参数。
接下来,为查询字符串参数指定键和值。
按照步骤完成规则的创建。
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 小时的待传送事件积压。为确保不会丢失任何事件,请设置一个死信队列,将调用失败的事件发送到该队列,以便日后可以处理这些事件。有关更多信息,请参阅事件重试策略和使用死信队列。