# 用自然语言撰写政策
<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 美元时，允许用户名为 “refund-agent” 的委托人处理退款。

 **转换为雪松：**

```
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: 写信更新覆盖范围”

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

禁止策略规定了用户不能执行的操作：
+ “阻止用户访问高灵敏度模型”
+ “拒绝初级承保人批准决定”
+ “在等待风险验证时，禁止用户处理退款”

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

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

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

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

 **示例场景：**

```
// 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>

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

灵活的表达方式：
+ “允许用户退款代理...”
+ “允许拥有用户名退款代理的用户...”
+ “扮演保险代理角色的用户可以...”
+ “任何拥有退款:write 范围的人都有权...”
+ “所有用户都可以...”

具体说明身份：

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

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

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

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

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

请具体说明该工具：

模糊：❌ “允许用户访问模型”

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

### 条件规范
<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>

允许范围为 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万时”
+ “当索赔超过一千万美元时”
+ “当乘客人数正好是 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 的用户更新覆盖范围”

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

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

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

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