本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 速率限制 API 示例
以下示例展示了如何使用 Amazon CLI 和 Amazon Python SDK (Boto3) 管理速率限制。
## 创建每目标每秒请求数限制
以下示例创建了以每个目标为基础控制每秒请求数的速率限制。特定目标获得 100 RPS，所有其他目标各获得自己的 10 RPS 桶。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["targetName"]' \
--description "Per-target RPS limit" \
--entries '[
{
"dimensions": {"targetName": "my-high-traffic-target"},
"requests": [
{
"rate": 100,
"period": "second"
}
]
},
{
"dimensions": {"targetName": "*"},
"requests": [
{
"rate": 10,
"period": "second"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["targetName"],
description="Per-target RPS limit",
entries=[
{
"dimensions": {"targetName": "my-high-traffic-target"},
"requests": [
{
"rate": 100,
"period": "second",
}
],
},
{
"dimensions": {"targetName": "*"},
"requests": [
{
"rate": 10,
"period": "second",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 创建每位来电者的每分钟请求数限制
以下示例根据调用方的 JWT `sub` 声明创建速率限制。高级用户获得 300 RPM，所有其他用户获得 60 RPM。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["$.context.jwt.sub"]' \
--description "Per-caller RPM by subscription tier" \
--entries '[
{
"dimensions": {"$.context.jwt.sub": "premium-user-001"},
"requests": [
{
"rate": 300,
"period": "minute"
}
]
},
{
"dimensions": {"$.context.jwt.sub": "premium-user-002"},
"requests": [
{
"rate": 300,
"period": "minute"
}
]
},
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [
{
"rate": 60,
"period": "minute"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["$.context.jwt.sub"],
description="Per-caller RPM by subscription tier",
entries=[
{
"dimensions": {"$.context.jwt.sub": "premium-user-001"},
"requests": [
{
"rate": 300,
"period": "minute",
}
],
},
{
"dimensions": {"$.context.jwt.sub": "premium-user-002"},
"requests": [
{
"rate": 300,
"period": "minute",
}
],
},
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [
{
"rate": 60,
"period": "minute",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 使用代币创建多维限制
以下示例使用三维密钥创建了速率限制，该限制了每分钟的请求和令牌。每个来电者都有自己的预算范围限定在特定的目标和型号上。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["targetName", "qualifiedModelId", "$.context.jwt.sub"]' \
--description "Per-caller token and request budget per target and model" \
--entries '[
{
"dimensions": {"targetName": "my-inference-target", "qualifiedModelId": "anthropic.claude-3-sonnet-20240229-v1:0", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "minute"
}
],
"tokens": [
{
"rate": 50000,
"period": "minute"
}
]
},
{
"dimensions": {"targetName": "*", "qualifiedModelId": "*", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 30,
"period": "minute"
}
],
"tokens": [
{
"rate": 10000,
"period": "minute"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["targetName", "qualifiedModelId", "$.context.jwt.sub"],
description="Per-caller token and request budget per target and model",
entries=[
{
"dimensions": {"targetName": "my-inference-target", "qualifiedModelId": "anthropic.claude-3-sonnet-20240229-v1:0", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "minute",
}
],
"tokens": [
{
"rate": 50000,
"period": "minute",
}
],
},
{
"dimensions": {"targetName": "*", "qualifiedModelId": "*", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 30,
"period": "minute",
}
],
"tokens": [
{
"rate": 10000,
"period": "minute",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 创建连接速率限制
以下示例为每个模型创建连接速率限制。这限制了对每个模型的并发运行中请求的数量，这对于保护并发容量有限的目标很有用。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["qualifiedModelId"]' \
--description "Connection rate limit per model" \
--entries '[
{
"dimensions": {"qualifiedModelId": "anthropic.claude-3-sonnet-20240229-v1:0"},
"connections": [
{
"rate": 50,
"period": "second"
}
]
},
{
"dimensions": {"qualifiedModelId": "*"},
"connections": [
{
"rate": 20,
"period": "second"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["qualifiedModelId"],
description="Connection rate limit per model",
entries=[
{
"dimensions": {"qualifiedModelId": "anthropic.claude-3-sonnet-20240229-v1:0"},
"connections": [
{
"rate": 50,
"period": "second",
}
],
},
{
"dimensions": {"qualifiedModelId": "*"},
"connections": [
{
"rate": 20,
"period": "second",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 屏蔽速率为零的来电者
以下示例通过将特定来电者的速率设置为 0 来屏蔽他们。更改传播后（最长 30 秒），这将拒绝来自被屏蔽呼叫方的所有请求。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["$.context.jwt.sub"]' \
--description "Block abusive caller" \
--entries '[
{
"dimensions": {"$.context.jwt.sub": "blocked-user-789"},
"requests": [
{
"rate": 0,
"period": "second"
}
]
},
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "second"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["$.context.jwt.sub"],
description="Block abusive caller",
entries=[
{
"dimensions": {"$.context.jwt.sub": "blocked-user-789"},
"requests": [
{
"rate": 0,
"period": "second",
}
],
},
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "second",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 通过具有身份共维度的请求标头进行速率限制
以下示例是调用者提供的`X-Customer-Id`请求标头的速率限制，范围限于经过身份验证的调用方。由于标头值由调用方提供，因此速率限制还包括`$.context.jwt.sub`身份共维度（自定义请求标头和正文维度是必需的，请参阅[自定义请求标头和正](gateway-rate-limits-dimensions.md#gateway-rate-limits-dimensions-custom-context)文维度）。携带的请求每个呼叫者`X-Customer-Id: premium`获得 100 个 RPS；所有其他标头值的每个呼叫者都有自己的 10 个 RPS 存储桶。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control create-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--dimension-keys '["$.context.request.header.X-Customer-Id", "$.context.jwt.sub"]' \
--description "Per-caller limit by customer tier header" \
--entries '[
{
"dimensions": {"$.context.request.header.X-Customer-Id": "premium", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "second"
}
]
},
{
"dimensions": {"$.context.request.header.X-Customer-Id": "*", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 10,
"period": "second"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.create_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
dimensionKeys=["$.context.request.header.X-Customer-Id", "$.context.jwt.sub"],
description="Per-caller limit by customer tier header",
entries=[
{
"dimensions": {"$.context.request.header.X-Customer-Id": "premium", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 100,
"period": "second",
}
],
},
{
"dimensions": {"$.context.request.header.X-Customer-Id": "*", "$.context.jwt.sub": "*"},
"requests": [
{
"rate": 10,
"period": "second",
}
],
},
],
)
print(f"Rate Limit ID: {response['rateLimitId']}")
```
## 获取速率限制
以下示例检索特定速率限制的详细信息。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control get-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--rate-limit-id rl-abc123def456
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.get_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
rateLimitId="rl-abc123def456",
)
print(f"Status: {response['status']}")
print(f"Dimension Keys: {response['dimensionKeys']}")
print(f"Entries: {len(response['entries'])}")
```
## 更新速率限制
以下示例更新了现有速率限制的条目，以提高特定目标的速率。
**注意**
该`dimensionKeys`字段在创建后不可变。要更改维度密钥，请删除速率限制并创建一个新的速率限制。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control update-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--rate-limit-id rl-abc123def456 \
--description "Updated per-target RPS limit" \
--entries '[
{
"dimensions": {"targetName": "my-high-traffic-target"},
"requests": [
{
"rate": 200,
"period": "second"
}
]
},
{
"dimensions": {"targetName": "*"},
"requests": [
{
"rate": 20,
"period": "second"
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.update_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
rateLimitId="rl-abc123def456",
description="Updated per-target RPS limit",
entries=[
{
"dimensions": {"targetName": "my-high-traffic-target"},
"requests": [
{
"rate": 200,
"period": "second",
}
],
},
{
"dimensions": {"targetName": "*"},
"requests": [
{
"rate": 20,
"period": "second",
}
],
},
],
)
print(f"Status: {response['status']}")
```
## 列出速率限制
以下示例列出了网关的所有速率限制。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control list-gateway-rate-limits \
--gateway-identifier my-gateway-abc1234567
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
paginator = client.get_paginator("list_gateway_rate_limits")
for page in paginator.paginate(gatewayIdentifier="my-gateway-abc1234567"):
for rate_limit in page["rateLimits"]:
print(
f"ID: {rate_limit['rateLimitId']}, "
f"Status: {rate_limit['status']}, "
f"Dimensions: {rate_limit['dimensionKeys']}"
)
```
**注意**
结果可能会被分页。使用响应中的`nextToken`值来检索其他页面，或使用 Boto3 分页器，如上所示。
## 删除速率限制
以下示例从网关删除速率限制。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control delete-gateway-rate-limit \
--gateway-identifier my-gateway-abc1234567 \
--rate-limit-id rl-abc123def456
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.delete_gateway_rate_limit(
gatewayIdentifier="my-gateway-abc1234567",
rateLimitId="rl-abc123def456",
)
print(f"Status: {response['status']}")
```
## Batch put 费率限制
以下示例在一次调用中创建或更新多个速率限制。Batch put 使用 upsert 语义——如果存在具有相同维度键的速率限制，则会对其进行更新；否则，将创建新的速率限制。
**注意**
Batch put 是等效的。您可以放心地重试失败的呼叫，而无需创建重复的速率限制。
**Example**
1. 运行以下命令：
```
aws bedrock-agentcore-control batch-put-gateway-rate-limits \
--gateway-identifier my-gateway-abc1234567 \
--rate-limits '[
{
"dimensionKeys": ["targetName"],
"description": "Per-target RPS",
"entries": [
{
"dimensions": {"targetName": "*"},
"requests": [{"rate": 50, "period": "second"}]
}
]
},
{
"dimensionKeys": ["$.context.jwt.sub"],
"description": "Per-caller RPM",
"entries": [
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [{"rate": 120, "period": "minute"}]
}
]
}
]'
```
1.
```
import boto3
client = boto3.client("bedrock-agentcore-control", region_name="us-west-2")
response = client.batch_put_gateway_rate_limits(
gatewayIdentifier="my-gateway-abc1234567",
rateLimits=[
{
"dimensionKeys": ["targetName"],
"description": "Per-target RPS",
"entries": [
{
"dimensions": {"targetName": "*"},
"requests": [
{"rate": 50, "period": "second"}
],
}
],
},
{
"dimensionKeys": ["$.context.jwt.sub"],
"description": "Per-caller RPM",
"entries": [
{
"dimensions": {"$.context.jwt.sub": "*"},
"requests": [
{"rate": 120, "period": "minute"}
],
}
],
},
],
)
for result in response["rateLimits"]:
print(f"ID: {result['rateLimitId']}, Status: {result['status']}")
```