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

# 速率限制维度
<a name="gateway-rate-limits-dimensions"></a>

维度密钥决定网关如何将流量分组到速率限制桶中。每个维度键都引用请求上下文中的一个值。网关在运行时解析这些值以找到匹配的速率限制条目。

## 支持的维度
<a name="gateway-rate-limits-dimensions-supported"></a>


| 维度键 | 说明 | 示例值 | 
| --- | --- | --- | 
|  `targetName`  | 正在调用的目标的名称。已从请求路径中解决。 |  `my-llm-target`  | 
|  `toolName`  | 正在调用的工具的完全限定名称，格式`targetName___toolName`为。适用于 MCP 工具使用请求。 |  `my-mcp-target___get_weather`  | 
|  `qualifiedModelId`  | 推理目标的完全限定模型标识符。 |  `anthropic.claude-3-sonnet-20240229-v1:0`  | 
|  `$.context.jwt.<claim>`  | 从调用者的 JWT 令牌中提取的声明。`<claim>`替换为索赔名称（例如`$.context.jwt.sub`、`$.context.jwt.team`）。 |  `user-123`  | 
|  `$.context.iam.principal`  | 来电者的 IAM 委托人 ARN。 |  `arn:aws:iam::123456789012:role/MyRole`  | 
|  `$.context.iam.sourceIdentity`  | 调用者在担任角色时设置的源身份。 |  `developer@example.com`  | 
|  `$.context.request.header.<name>`  | 来电者提供的请求标头的值。`<name>`替换为标题名称（例如，`$.context.request.header.X-Customer-Id`）。标头名称匹配不区分大小写。需要具有相同速率限制的可信身份共维度——请参阅[自定义请求标题和正文维度](#gateway-rate-limits-dimensions-custom-context)。 |  `premium`  | 
|  `$.context.request.body.<path>`  | JSON 请求正文中字段的值，由简单的虚线路径寻址。`<path>`替换为虚线字段路径（例如，`$.context.request.body.metadata.tier`）。需要具有相同速率限制的可信身份共维度——请参阅[自定义请求标题和正文维度](#gateway-rate-limits-dimensions-custom-context)。 |  `batch`  | 

## 自定义请求标头和正文尺寸
<a name="gateway-rate-limits-dimensions-custom-context"></a>

该`$.context.request.header.<name>`维度按来电者提供的请求标头对流量进行分组。该`$.context.request.body.<path>`维度按照 JSON 请求正文中的字段对流量进行分组。例如，您可以按`X-Customer-Id`标头中传递的租户级别或请求正文中的`workload_type`字段进行速率限制。

### 必需的身份共同维度
<a name="gateway-rate-limits-dimensions-custom-context-codimension"></a>

由于调用方提供标头或正文值，因此不能单独使用自定义请求标头或正文维度。使用这些维度之一的每个速率限制还必须包含具有相同速率限制的可信身份共维度，以便每个存储桶的范围限定为经过身份验证的身份：
+ 对于采用 IAM (Sigv4) 入站身份验证的网关，请包括一个`$.context.iam.*`维度（例如）。`$.context.iam.principal`
+ 对于采用 OAuth (JWT) 入站身份验证的网关，请包括一个`$.context.jwt.<claim>`维度（例如）。`$.context.jwt.sub`

网关拒绝一个速率限制，该限制指定了没有匹配身份共维的自定义请求标头或正文维度，`ValidationException`并在创建时返回。网关的入站身份验证必须可绑定到 IAM 或 JWT 身份才能使用这些维度。例如，未配置入站身份验证的网关不能使用自定义请求标头或正文尺寸。

**注意**  
身份共同维度可以出现在`dimensionKeys`相对于标题或正文维度的任何位置；它只需要出现在相同的速率限制中即可。

### 选择器语法和值约束
<a name="gateway-rate-limits-dimensions-custom-context-syntax"></a>

自定义请求标头和正文选择器使用固定的字段指针语法 — 不支持 JSONPath 运算符（例如过滤器、通配符或数组切片）：
+ 标头选择器是`$.context.request.header.<name>`，其中`<name>`是单个 HTTP 标头名称。
+ 主体选择器是`$.context.request.body.<path>`，其中`<path>`是对象字段名称的虚线路径（例如，`metadata.customer.tier`）。每个分段都处理一个嵌套的 JSON 对象字段；最后一段必须解析为标量（字符串、数字或布尔值）值。
+ 一个选择器最多可以包含 128 个字符。

在运行时，网关会解析该值并应用以下规则，然后再将其用作存储桶密钥：
+ 删除了前导和尾随的空格。值区分大小写，否则将完全按照提供的方式使用（例如，`gold`和`Gold`是不同的值）。
+ 解析后的值最多可为 256 个字符，且不得包含`/``|``,`、、、`*`字符或控制字符。违反这些规则的值会导致该请求跳过该维度（请参阅[维度解析行为](#gateway-rate-limits-dimensions-resolution)）。

## 默认值 (`*`)
<a name="gateway-rate-limits-dimensions-default-value"></a>

速率限制条目支持将特殊值`*`作为维度的包罗万象的默认值。
+ 一个维`*`度的条目意味着 “将此比率应用于该维度的所有值”。
+ 如果实际值存在更具体的条目，则该特定条目优先（最具体的匹配项获胜）。
+  `*`为每个实体创建独立的存储桶 — 每个匹配的不同值都会按配置的费率获得自己的费率桶。

 **Trailing-only 多维速率限制的约束：**

当速率限制有多个维度键时，` `只能出现在尾随位置。如果``在位置 N 处使用，则所有后续位置也必须是`*`。

例如，用`dimensionKeys: ["targetName", "toolName", "$.context.jwt.sub"]`：


| 入口尺寸 | 有效 | 为什么 | 
| --- | --- | --- | 
|  `["target1", "readData", "alice"]`  | 是 | 所有位置都是特定的值。 | 
|  `["target1", "readData", "*"]`  | 是 | 只有最后一个位置是`*`。 | 
|  `["target1", "*", "*"]`  | 是 | 尾随头寸是。`*` | 
|  `["*", "*", "*"]`  | 是 | 所有位置均为`*`（任意组合的默认位置）。 | 
|  `["*", "readData", "alice"]`  | 否 |  `*`在位置 1，后面是特定值。 | 
|  `["*", "*", "alice"]`  | 否 |  `*`在位置 1-2 处，然后是特定值。 | 
|  `["target1", "*", "alice"]`  | 否 |  `*`在位置 2，然后在位置 3 处输入特定值。 | 

 **匹配的工作原理：**

当请求到达时，网关会解析实际的维度值并寻找最具体的匹配条目。例如，如果解析的值是`["target1", "readData", "alice"]`，则网关将按以下顺序检查条目：

1.  `["target1", "readData", "alice"]`— 完全匹配（最具体）

1.  `["target1", "readData", "*"]`— 最后一个维度使用默认值

1.  `["target1", "*", "*"]`— 最后两个维度使用默认值

1.  `["*", "*", "*"]`— 完全默认（最不具体）

第一场比赛获胜。

**提示**  
对于已知的高价值实体或受限实体，使用特定`*`条目作为其他所有实体的默认费率等级。

## 尺寸分辨率行为
<a name="gateway-rate-limits-dimensions-resolution"></a>

当网关评估速率限制时，它会解析请求上下文中的每个维度密钥：
+ 如果无法从请求中解析维度密钥（例如，`toolName`在非工具请求或不存在的 JWT 声明中），则网关将完全跳过该速率限制。该请求不受该速率限制的限制。
+ 当无法将值解析为可用值时，会以相同的方式跳过自定义请求标头或正文维度。当标头不存在、请求正文不是有效的 JSON、虚线路径不存在或无法解析为标量，或者解析的值违反了值约束时，就会发生这种情况（请参阅[选择器语法和值约束](#gateway-rate-limits-dimensions-custom-context-syntax)）。
+ 仅使用经过验证的上下文进行解析。JWT 声明是从经过网关身份验证配置验证的令牌中提取的。IAM 上下文仅适用于 SigV4-authenticated 请求。

## 共享限制与个人限制
<a name="gateway-rate-limits-dimensions-shared-vs-individual"></a>

维度键和条目值的组合决定了流量是共享一个费率桶，还是每个实体都有自己的独立存储桶。


| 维度键 | 入口尺寸 | 行为 | 
| --- | --- | --- | 
|  `["targetName"]`  |  `{"targetName": "my-target"}`  | 所有流向的流量`my-target`共享一个存储桶（该目标的共享限制）。 | 
|  `["targetName"]`  |  `{"targetName": "*"}`  | 每个目标都会按此速率获得自己的独立存储桶（每个实体）。 | 
|  `["$.context.jwt.sub"]`  |  `{"$.context.jwt.sub": "*"}`  | 每个唯一的来电者都有自己的存储桶（每个来电者的个人限制）。 | 
|  `["targetName", "$.context.jwt.sub"]`  |  `{"targetName": "my-target", "$.context.jwt.sub": "*"}`  | 每个呼叫者都有自己的存储桶，范围限定为。`my-target` | 
|  `["targetName", "$.context.jwt.sub"]`  |  `{"targetName": "*", "$.context.jwt.sub": "*"}`  | 每个独特的目标和召唤者组合都有自己的存储桶。 | 

**警告**  
避免使用高基数或无界维度值作为维度键，例如 JWT 声明（如`$.context.jwt.jti`或）`$.context.jwt.nonce`，或者自定义请求 header/body 选择器，这些选择器带有每个请求的唯一值，例如请求 ID、跟踪 ID 或 UUID（例如）。`$.context.request.header.X-Request-Id`它们会产生无限数量的费率桶，这可能会降低速率限制的有效性。`tier`改用稳定的有界标识符`sub`，例如`team`、或。