View a markdown version of this page

速率限制維度 - Amazon Bedrock 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

預設值 (*)

速率限制項目支援特殊值*做為維度的截獲預設值。

  • 具有 *的維度項目表示「將此速率套用至此維度的所有值」。

  • 如果實際值有更具體的項目，則以特定項目為優先 （最具體的配對獲勝）。

  • * 會建立獨立的每個實體儲存貯體 — 符合的每個不同值都會以設定的速率取得自己的速率儲存貯體。

多維度速率限制的追蹤限定條件：

當速率限制具有多個維度索引鍵時， 只能顯示在結尾位置。如果您在位置 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請求。

共用與個別限制

維度索引鍵和項目值的組合會決定流量是共用單一速率儲存貯體，還是每個實體都會取得自己的獨立儲存貯體。

dimensionKeys 項目維度 Behavior (行為)

["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": "*"}

每個唯一的target-and-caller組合都會取得自己的儲存貯體。
警告

避免使用高基數或未限制的 JWT 宣告做為維度索引鍵 （例如 $.context.jwt.jti、 $.context.jwt.nonce或 請求 IDs)。這些會建立無限制的速率儲存貯體數量，這可能會降低速率限制的有效性。請tier改用穩定的邊界識別符，例如 sub、 team或 。