View a markdown version of this page

速率限制维度 - 亚马逊基岩 AgentCore
支持的维度默认值 (*)维度分辨率行为共享限额与个人限额

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

速率限制维度

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

支持的维度

维度键 说明 示例值

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

默认值 (*)

速率限制条目支持将特殊值*作为维度的通用默认值。

  • 一个维*度的条目表示 “将此比率应用于该维度的所有值”。

  • 如果实际值存在更具体的条目，则该特定条目优先（最具体的匹配获胜）。

  • *创建独立的每个实体存储桶——每个匹配的不同值都将按配置的费率获得自己的费率区间。

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"]— 精确匹配（最具体）

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

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

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

第一场比赛获胜。

提示

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

维度分辨率行为

当网关评估速率限制时，它会解析请求上下文中的每个维度密钥：

  • 如果无法从请求中解析维度密钥（例如，toolName非工具请求或不存在的 JWT 声明），则网关将完全跳过该速率限制。该请求不受该速率限制的限制。

  • 只有经过验证的上下文才用于解析。JWT 声明是从经过网关身份验证配置验证的令牌中提取的。IAM 上下文仅适用于 SigV4-authenticated 请求。

共享限额与个人限额

维度键和输入值的组合决定了流量是共享一个费率区间还是每个实体都有自己的独立分区。

维度键 入口尺寸 行为

["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、或请求 ID）。它们会创建无限数量的速率区间，这可能会降低速率限制的有效性。tier改用稳定的有界标识符sub，例如team、或。