View a markdown version of this page

向网关添加规则 - Amazon Bedrock AgentCore
网关规则的工作原理规则解析Conditions操作限制

向网关添加规则

网关规则允许您控制流量路由，并覆盖网关上的目标配置，而无需重新部署目标。您可以创建覆盖目标行为的配置包，然后使用规则来控制哪个捆绑包版本适用于哪些流量。规则还支持根据请求路径或呼叫者身份将请求路由到不同的目标。

使用网关规则来实现以下目标：

  • 通过 A/B 测试对配置包版本进行试验

  • 将特定主体固定到配置包版本以进行调试

  • 根据请求路径或呼叫者身份将流量路由到特定目标

  • 为所有流量设置默认配置包或目标

网关规则的工作原理

每条网关规则都包含以下组件：

组件 说明

优先级

从 1 到 1,000,000 之间的整数。数字越小表示优先级越高。每个优先级值在网关中必须是唯一的。

条件（可选）

确定规则是否与请求匹配的标准。没有条件的规则充当匹配所有流量的包罗万象。

操作（必填）

规则匹配时要采取的操作。您可以覆盖配置包、路由到特定目标，或者两者兼而有之。

Description（可选）

对规则目的的文字描述。

规则解析

网关按优先级升序评估规则（数字越小）。网关使用第一匹配语义独立解析每种操作类型。

下表显示了网关如何解析示例请求的规则。在此示例中，QA 角色向发送请求/my-target-canary/chat。

优先级 Conditions 操作 匹配请求？ 结果

100

质量保证角色

configurationBundle: 捆绑包版本 A

是

已解析configurationBundle为版本 A

200

路径 /my-target-canary/*

routeToTarget: my-target-canary

是

决心为 routeToTarget my-target-canary

1000000

无（包罗万象）

configurationBundle: 捆绑包版本 B，routeToTarget: my-target-primary

是

两种操作类型都已解决。已跳过。

最终结果：请求使用捆绑包版本 A 并路由到my-target-canary。

提示

在优先级数字（例如 100、200、300）之间留出间隔，这样您就可以稍后插入规则，而无需对现有规则进行重新编号。

Conditions

条件决定了规则匹配哪些请求。一条规则最多可以有 2 个条件。没有条件的规则匹配所有流量。

网关支持以下条件类型：

匹配校长

根据呼叫者的 IAM 委托人匹配请求。该anyOf列表包含 1 到 100 个条目。每个条目都指定一个iamPrincipal，其中包含以下字段：

  • arn— 要匹配的 IAM 委托人 ARN。

  • operator（可选）-比较运算符。有效值为 StringEquals（默认值）和 StringLike。StringLike用于通配符匹配。

匹配路径

根据请求路径匹配请求。该anyOf列表包含 1 到 10 个条目。每个条目都必须使用格式/<targetName>/*，其中<targetName>与网关上现有 HTTP 目标的名称相匹配。目标必须处于Ready状态。只有具有 HTTP 目标的网关才支持该matchPaths条件。不允许使用以下保留路径前缀：/mcp、、/a2a、/responses/converse、/.well-known。

条件评估逻辑

  • 在条件类型内：网关使用 OR 逻辑。如果请求满足anyOf列表中的任何条目，则该请求匹配。

  • 跨条件类型：网关使用 AND 逻辑。如果规则同时包含matchPrincipals和matchPaths，则请求必须与每种条件类型中的至少一个条目相匹配。

操作

操作定义了规则匹配时网关的操作。一条规则最多可以有 2 个操作。

网关支持以下操作类型：

配置包覆盖 () configurationBundle

覆盖应用于匹配流量的配置包。

  • staticOverride— 将所有匹配的流量固定到特定的配置包版本。指定捆绑包 ARN 和版本 ID。

  • weightedOverride— 在两个配置包版本之间拆分流量。该trafficSplit列表必须恰好包含 2 个权重总和为 100 的条目。配置包必须与网关在同一个账户中。

目标路由 (routeToTarget)

将匹配的流量路由到特定目标。目标必须使用 HTTP 协议并且处于Ready状态。

  • staticRoute— 按名称将所有匹配的流量路由到特定目标。

  • weightedRoute— 在两个目标之间分配流量。该trafficSplit列表必须恰好包含 2 个权重总和为 100 的条目。流量分割条目名称必须是唯一的。

限制

下表列出了网关规则的限制。

资源 限制

每个网关的规则

20

优先级范围

1 到 1,000,000

每条规则的最大条件数

2

每条规则的最大操作数

2

matchPrincipals.anyOf最大条目数

100

matchPaths.anyOf最大条目数

10

trafficSplit条目

正好 2

trafficSplit重量范围

1 到 99
主题