# 批次評估加密
當您在批次評估`kmsKeyArn`上指定 時，服務會使用 S3 伺服器端加密搭配 KMS (SSE-KMS) 來加密存放在 S3 中的所有輸出成品。這包括資料來源組態、工作階段中繼資料和評估結果。
`kmsKeyArn` 是在建立時間透過 指定`StartBatchEvaluation`。
## 運作方式
批次評估加密使用 S3 SSE-KMS。當服務在 S3 中寫入或讀取批次評估輸出時，S3 會代表服務呼叫 KMS 來加密或解密資料。服務主體 (`bedrock-agentcore.amazonaws.com`) 必須在金鑰政策中具有 KMS 許可。
在 API 時間，服務會使用試轉檢查 （正向存取工作階段） 驗證發起人是否具有 KMS 許可。這會立即擷取許可問題，而不是在批次評估工作流程期間非同步失敗。
服務也會驗證其可以使用`kms:GenerateDataKey`自己的登入資料執行 ，以確保金鑰政策授予服務委託人寫入加密輸出所需的許可。
AgentCore Evaluations 僅支援對稱加密 KMS 金鑰。KMS 金鑰必須與批次評估位於相同的 AWS 區域。
### 設定使用客戶受管 KMS 金鑰的許可
下列金鑰政策提供批次評估加密所需的最低許可。此政策有三個陳述式：
+ **AllowCallerAccess** – 允許 IAM 使用者或角色透過 驗證金鑰`DescribeKey`。
+ **AllowCallerCryptoOps** – 允許 IAM 使用者或角色加密和解密，範圍依加密內容而定。
+ **AllowServicePrincipalAccess** – 允許 AgentCore 服務主體加密和解密 S3 中的批次評估資料，範圍依來源帳戶和來源 ARN 而定。
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowCallerAccess",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": "kms:DescribeKey",
"Resource": "*"
},
{
"Sid": "AllowCallerCryptoOps",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:role/MyBatchEvaluationRole"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringLike": {
"kms:EncryptionContext:aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
}
}
},
{
"Sid": "AllowServicePrincipalAccess",
"Effect": "Allow",
"Principal": {
"Service": "bedrock-agentcore.amazonaws.com"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "111122223333"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*"
}
}
}
]
}
```
此政策包含下列陳述式：
+ **AllowCallerAccess** – 在批次評估建立時間授予金鑰驗證的 IAM 角色`kms:DescribeKey`許可。將 {{111122223333}} 取代為您的帳戶 ID，並將 {{MyBatchEvaluationRole}} 取代為啟動批次評估的 IAM 角色或使用者。
+ **AllowCallerCryptoOps** – 授予加密`aws:bedrock-agentcore:batchEvaluationArn`內容範圍內的 IAM 角色`kms:GenerateDataKey`和`kms:Decrypt`許可。將 {{111122223333}}、{{MyBatchEvaluationRole}} 和 {{us-east-1}} 取代為您的值。若要允許存取您帳戶中的所有批次評估，請使用萬用字元搭配 `StringLike`：`arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/*`。
+ **AllowServicePrincipalAccess** – 授予 AgentCore 服務主體`kms:GenerateDataKey`和`kms:Decrypt`許可，以加密和解密 S3 中的批次評估資料。由來源帳戶和來源 ARN (`aws:SourceArn`) 範圍，以防止混淆代理人攻擊。將 {{us-east-1}} 和 {{111122223333}} 取代為您的區域和帳戶 ID。
### 縮小對客戶受管 KMS 金鑰的存取範圍
您可以使用加密內容來縮小對客戶受管金鑰的存取範圍。AgentCore Evaluations 在所有 KMS 操作中包含下列加密內容：
```
{
"aws:bedrock-agentcore:batchEvaluationArn": "arn:aws:bedrock-agentcore:us-east-1:111122223333:batch-evaluate/batch-evaluation-id"
}
```
您可以在金鑰政策條件中使用此加密內容，將 KMS 操作限制為特定批次評估，如上述範例金鑰政策中的 `AllowCallerCryptoOps`陳述式所示。請注意， `AllowServicePrincipalAccess` 使用 `aws:SourceArn`進行範圍界定，而非加密內容。
## 使用客戶受管 KMS 金鑰開始批次評估
呼叫 時指定 `kmsKeyArn` 參數`StartBatchEvaluation`：
**Example**
使用 AgentCore CLI，使用 `--kms-key`選項指定單一 KMS 金鑰 ARN 來加密批次評估結果。AgentCore CLI 使用 `--kms-key`旗標，這與 AWS CLI 的`--kms-key-arn`旗標和 boto3 `kmsKeyArn` 參數不同。
```
agentcore run batch-evaluation \
-r MyAgent \
-e Builtin.Correctness \
--kms-key arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab
```
```
aws bedrock-agentcore start-batch-evaluation \
--batch-evaluation-name "MyEncryptedBatchEval" \
--kms-key-arn "arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab" \
--evaluators '[{"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness"}]' \
--data-source-config '{
"cloudwatchLogs": {
"logGroupNames": ["/aws/bedrock-agentcore/sessions/my-agent"],
"serviceNames": ["my-agent.DEFAULT"],
"filterConfig": {
"timeRange": {
"startTime": "2025-01-01T00:00:00Z",
"endTime": "2025-01-02T00:00:00Z"
}
}
}
}'
```
```
import boto3
client = boto3.client('bedrock-agentcore')
response = client.start_batch_evaluation(
batchEvaluationName='MyEncryptedBatchEval',
kmsKeyArn='arn:aws:kms:us-east-1:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
evaluators=[{'evaluatorArn': 'arn:aws:bedrock-agentcore:::evaluator/Builtin.Helpfulness'}],
dataSourceConfig={
'cloudwatchLogs': {
'logGroupNames': ['/aws/bedrock-agentcore/sessions/my-agent'],
'serviceNames': ['my-agent.DEFAULT'],
'filterConfig': {
'timeRange': {
'startTime': '2025-01-01T00:00:00Z',
'endTime': '2025-01-02T00:00:00Z'
}
}
}
}
)
print(f"Batch Evaluation ID: {response['batchEvaluationId']}")
```
## 監控批次評估的 KMS 用量
批次評估 KMS 操作會顯示下列 CloudTrail 事件名稱：
+ `GenerateDataKey` — 將加密的批次評估輸出寫入 S3 時 （資料來源組態、工作階段中繼資料、評估結果）。`encryptionContext` 欄位包含 `aws:bedrock-agentcore:batchEvaluationArn`。
+ `Decrypt` — 從 S3 讀取加密批次評估輸出時。
+ `DescribeKey` — 在批次評估建立時間驗證金鑰時。
如需監控 KMS 用量的詳細資訊，請參閱 * AWS Key Management Service 開發人員指南*中的[使用 AWS CloudTrail 記錄 AWS KMS API 呼叫](https://docs.aws.amazon.com/kms/latest/developerguide/logging-using-cloudtrail.html)。
## 當金鑰無法使用時的行為
如果您停用或刪除批次評估所使用的客戶受管 KMS 金鑰：
+ **StartBatchEvaluation** — 使用 驗證時失敗`ValidationException`。
+ **GetBatchEvaluation** — 傳回中繼資料 （名稱、狀態、時間戳記），但服務無法讀取存放在加密 S3 物件中的評估結果。
+ **ListBatchEvaluations** — 成功，因為列出只會傳回中繼資料，不需要 KMS 操作。
+ **StopBatchEvaluation** — 成功，因為停止不需要解密資料。
+ **DeleteBatchEvaluation** — 成功，因為 S3 物件刪除不需要 KMS 解密。
若要還原存取權，請重新啟用金鑰或更新金鑰政策，以授予所需的許可。
上述批次評估生命週期操作會映射至 AgentCore CLI 命令。`stop` 和 `archive`命令會透過 `-i, --id `選項以任務為目標。`view batch-evaluation` 命令以 ID 做為位置引數：
+ **StartBatchEvaluation** — `agentcore run batch-evaluation --kms-key `（使用 `-r/--runtime`和 `-e/--evaluator`)
+ **GetBatchEvaluation** — `agentcore view batch-evaluation `
+ **ListBatchEvaluations** — `agentcore view batch-evaluation`或 `agentcore batch-evaluations history`
+ **StopBatchEvaluation** — `agentcore stop batch-evaluation -i `
+ **DeleteBatchEvaluation** — `agentcore archive batch-evaluation -i `