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

# 用自然语言撰写政策
<a name="policy-natural-language"></a>

Polic AgentCore y in 将自动选择您所在地理区域内的最佳区域，以处理您通过策略创作服务提出的推理请求。这样可以最大限度地利用可用计算资源、模型可用性，并提供最佳的客户体验。您的数据将仅存储在发起请求的区域，但是，输入提示和输出结果可能会在该区域之外进行处理。所有数据都将通过 Amazon 的安全网络进行加密传输。

中的策略 AgentCore 将安全地将您的推理请求路由到请求发起的地理区域内的可用计算资源，如下所示：
+ 来自欧盟的推理请求将在欧盟内部处理。
+ 源自美国的推理请求将在美国境内处理。
+ 源自亚太地区的推理请求将在亚太地区内处理。

**Topics**
+ [概述](#nl2cedar-overview)
+ [示例](#nl2cedar-example)
+ [政策影响](#nl2cedar-policy-effects)
+ [授权语义](#nl2cedar-authorization-semantics)
+ [策略元素](#nl2cedar-policy-elements)
+ [策略示例](#nl2cedar-policy-examples)
+ [条件语法](#nl2cedar-condition-syntax)
+ [组合条件](#nl2cedar-combining-conditions)
+ [常见陷阱](#nl2cedar-common-pitfalls)

## 概述
<a name="nl2cedar-overview"></a>

Cedar 提供精确的访问控制，但需要学习正式语法。nl2Cedar 使您能够：

1. 用自然语言写授权要求

1. 自动转换为 Cedar 语法

1. 验证生成的策略是否符合您的要求

**注意**  
自然语言策略生成需要部署 AgentCore 网关和策略引擎。该服务使用 AgentCore 网关架构来生成有效的 Cedar 策略。有关设置说明， AgentCore[请参阅中的策略](policy-getting-started.md)入门。

**注意**  
自然语言很灵活，但精确度对安全至关重要。政策必须明确、毫不含糊。

## 示例
<a name="nl2cedar-example"></a>

上一节中的退款政策可以用自然语言表达：

 **自然语言：**

当退款金额低于500美元时，允许用户名为 “退款代理人” 的委托人处理退款。

 **转换为 Cedar：**

```
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"RefundTool___process_refund",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/refund-gateway"
)
when {
  principal.hasTag("username") &&
  principal.getTag("username") == "refund-agent" &&
  context.input.amount < 500
};
```

## 政策影响
<a name="nl2cedar-policy-effects"></a>

授权策略有两种可能的效果：允许和禁止。

**Topics**
+ [许可政策](#nl2cedar-permit-policies)
+ [禁止政策](#nl2cedar-forbid-policies)

### 许可政策
<a name="nl2cedar-permit-policies"></a>

许可策略规定了用户可以做什么：
+ “允许用户退款代理处理退款”
+ “允许拥有角色主管的用户批准决策”
+ “使用范围 admin: write 授权用户更新覆盖范围”

### 禁止政策
<a name="nl2cedar-forbid-policies"></a>

禁用政策规定了用户不能做的事情：
+ “阻止用户访问高灵敏度模型”
+ “拒绝初级承销商批准决定”
+ “禁止用户在风险验证待处理时处理退款”

## 授权语义
<a name="nl2cedar-authorization-semantics"></a>

了解 Cedar 如何评估政策对于编写有效的授权规则至关重要。Cedar 遵循三个基本原则：
+  **默认情况下，所有操作都被拒绝 **-如果没有任何策略明确允许某项操作，则会自动将其阻止
+  **Forbid 永远是赢家 **-如果任何禁止策略匹配，则即使许可政策也匹配，访问也会被拒绝
+  **至少需要一个许可证 **-要授予访问权限，必须至少有一个许可政策相匹配，并且任何禁止政策都无法匹配

 **如果默认情况下所有内容都被拒绝，为什么要使用禁止政策？** 

禁令政策确保不会错误地允许特定操作。即使有人制定了更广泛的许可政策，禁止政策也会优先考虑并阻止访问。

 **示例场景：**

```
// Broad permit policy - allows all users to view model results
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"ModelAPI___view_results",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/model"
);

// Forbid policy - blocks access to high-sensitivity results
forbid(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"ModelAPI___view_results",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-west-2:123456789012:gateway/model"
)
when {
  context.input.sensitivity == "high"
};
```

 **结果：**用户可以查看低灵敏度和中等灵敏度的结果（允许使用），但高灵敏度的结果始终会被屏蔽（禁止获胜）。

对以下情况使用禁用政策：
+ 明确的安全限制，绝不能被覆盖
+ 合规性要求
+ 紧急停机
+ 为更广泛的许可政策设定例外情况

## 策略元素
<a name="nl2cedar-policy-elements"></a>

授权策略需要三个关键要素：

1.  **谁 **-哪些用户或角色可以执行操作

1.  **什么 **-他们可以使用哪些操作或工具

1.  **何时 **-在什么条件或限制条件下

**Topics**
+ [主要规格](#nl2cedar-principal-specification)
+ [动作规范](#nl2cedar-action-specification)
+ [条件规范](#nl2cedar-condition-specification)

### 主要规格
<a name="nl2cedar-principal-specification"></a>

委托人确定该策略适用于哪些用户、角色或群组。

灵活的表达式：
+ “允许用户退款代理...”
+ “允许用户名为refund-agent的用户...”
+ “拥有角色保险代理人的用户可能...”
+ “任何拥有退款:写入范围的人都有权...”
+ “所有用户都可以...”

具体说明身份：

未完成：❌ “允许处理 500 美元以下的退款”

完成：✓ “允许退款代理处理 500 美元以下的退款”

### 动作规范
<a name="nl2cedar-action-specification"></a>

“内容” 确定了策略控制的操作、工具或操作。

灵活的动作动词：
+ “允许用户处理退款”
+ “许可退款处理”
+ “用户可以创建应用程序”
+ “授权查看审核日志”

请具体说明该工具：

Vague: ❌ “允许用户访问模型”

清除：✓ “允许数据科学团队访问分析模型”

### 条件规范
<a name="nl2cedar-condition-specification"></a>

“何时” 指明了该政策在什么情况下适用。

灵活的条件表达式：
+ “... 当金额低于 500 美元时”
+ “... 如果该地区是美国、加拿大或英国”
+ “... 仅当批准状态为经理批准时”
+ “... 前提是风险评分已经提交”

精确地描述条件：

模糊：❌ “在金额合理时允许转账”

精确：✓ “当金额低于 10,000 美元时允许转账”

## 策略示例
<a name="nl2cedar-policy-examples"></a>

以下示例演示如何使用明确的原则、行动和条件来构建自然语言政策。

**Topics**
+ [示例 1：简单 User-Based 策略](#nl2cedar-example-1)
+ [示例 2： Role-Based 使用多个条件](#nl2cedar-example-2)
+ [示例 3： Scope-Based 访问](#nl2cedar-example-3)
+ [示例 4：每个人都有约束条件](#nl2cedar-example-4)

### 示例 1：简单 User-Based 策略
<a name="nl2cedar-example-1"></a>

允许用户退款代理在金额低于 500 美元时处理退款。

元素：
+  **谁：**用户退款代理
+  **什么：**处理退款
+  **什么时候：**金额低于 500 美元

### 示例 2： Role-Based 使用多个条件
<a name="nl2cedar-example-2"></a>

允许拥有角色保险代理人的用户在保险类型为责任险或碰撞险且保单处于有效状态时更新承保范围。

元素：
+  **谁：拥有角色保险代理人的**用户
+  **内容：**更新覆盖范围
+  **何时：**保险类型为责任险或碰撞且保单处于有效状态

### 示例 3： Scope-Based 访问
<a name="nl2cedar-example-3"></a>

允许使用 scope travel: book 的用户在该地区不是欧盟且产品符合条件时创建航班预订。

元素：
+  **谁：**使用 scope 的用户 travel: book
+  **什么：**创建航班预订
+  **何时：**地区不是欧盟且商品符合条件

### 示例 4：每个人都有约束条件
<a name="nl2cedar-example-4"></a>

当数据敏感度为低或中等且结果类型为风险分数时，允许所有用户查看模型结果。

元素：
+  **谁：**所有用户
+  **什么：**查看模型结果
+  **何时：**数据敏感度低或中等且结果类型为风险分数

## 条件语法
<a name="nl2cedar-condition-syntax"></a>

条件是政策往往变得模棱两可的地方。以下是编写清晰、可测试的条件的方法。

**Topics**
+ [数字比较](#nl2cedar-numeric-comparisons)
+ [字符串匹配](#nl2cedar-string-matching)
+ [布尔值条件](#nl2cedar-boolean-conditions)
+ [场地存在](#nl2cedar-field-existence)

### 数字比较
<a name="nl2cedar-numeric-comparisons"></a>

很好的例子：
+ “当金额低于 500 美元时”
+ “当保险金额低于500万时”
+ “当索赔超过 10,000,000 美元时”
+ “当乘客人数正好是 2"

避免使用模糊的措辞：
+ ❌ “当金额很少时”
+ ❌ “当覆盖率高时”

### 字符串匹配
<a name="nl2cedar-string-matching"></a>

精确匹配：
+ “当该地区是美国时”
+ “当付款方式是信用卡时”
+ “当状态为批准时”

多个选项：
+ “当该地区为美国、加拿大或英国时”
+ “当决策类型为批准或推荐时”

图案匹配：
+ “当电子邮件包含 @example .com 时”
+ “当作用域包含 admin: write 时”

否定：
+ “当该地区不是欧盟时”
+ “当分类不受限制时”

### 布尔值条件
<a name="nl2cedar-boolean-conditions"></a>

直接检查：
+ “当产品符合条件时”
+ “提交风险评分时”
+ “当要求特快配送时”

否定：
+ “当产品不符合条件时”
+ “未提交风险评分时”

### 场地存在
<a name="nl2cedar-field-existence"></a>

必填字段：
+ “当提供原因时”
+ “当应用程序 ID 存在时”
+ “指定返回日期时”

## 组合条件
<a name="nl2cedar-combining-conditions"></a>

真正的政策通常需要多个条件。使用清晰的逻辑连接器。

**Topics**
+ [AND 逻辑（一切都必须是真的）](#nl2cedar-and-logic)
+ [OR 逻辑（必须至少有一个是真的）](#nl2cedar-or-logic)
+ [复杂逻辑](#nl2cedar-complex-logic)

### AND 逻辑（一切都必须是真的）
<a name="nl2cedar-and-logic"></a>

使用诸如：“和”、“还”、“另外”、“while”、“with” 之类的词语

示例：

当该地区为美国且产品符合条件且该地区处于活动状态时，允许申请。

### OR 逻辑（必须至少有一个是真的）
<a name="nl2cedar-or-logic"></a>

使用诸如：“或”、“或者”、“任意” 之类的词语

示例：

当索赔超过 10,000,000 美元或风险级别较高或严重时，允许批准。

### 复杂逻辑
<a name="nl2cedar-complex-logic"></a>

对于复杂的条件，请使用清晰的结构：

示例：

允许在工作流程阶段审阅完成或批准、合规状态已通过且权限为经理或主管时完成定稿。

## 常见陷阱
<a name="nl2cedar-common-pitfalls"></a>

在编写自然语言策略时，请避免这些常见错误，以确保它们正确地转换为 Cedar 语法。

**Topics**
+ [错误 1：模糊的校长](#nl2cedar-mistake-1)
+ [错误 2：模棱两可的动作](#nl2cedar-mistake-2)
+ [错误 3：主观条件](#nl2cedar-mistake-3)
+ [错误 4：缺少条件](#nl2cedar-mistake-4)
+ [错误 5：逻辑不明确](#nl2cedar-mistake-5)

### 错误 1：模糊的校长
<a name="nl2cedar-mistake-1"></a>

错误：“允许访问退款工具”

良好：“允许用户退款代理访问退款工具”

### 错误 2：模棱两可的动作
<a name="nl2cedar-mistake-2"></a>

错误：“允许用户访问数据”

良好：“允许用户查看患者记录”

### 错误 3：主观条件
<a name="nl2cedar-mistake-3"></a>

不好：“在金额合理时允许转账”

良好：“当金额低于 10,000 美元时允许转账”

### 错误 4：缺少条件
<a name="nl2cedar-mistake-4"></a>

错误：“允许具有 admin: write 作用域的用户更新覆盖范围”

良好：“允许具有 scope admin: write 的用户在保单生效且承保类型为责任或碰撞保险时更新承保范围”

### 错误 5：逻辑不明确
<a name="nl2cedar-mistake-5"></a>

错误：“当 A 或 B 和 C 时允许”

良好：“在（A 或 B）和 C 时允许” 或 “当 A 或（B 和 C）时允许”