# 以自然語言撰寫政策
<a name="policy-natural-language"></a>

AgentCore 中的政策會自動選取您地理位置內的最佳區域，以處理透過政策撰寫服務提出的推論請求。這可將可用的運算資源、模型可用性最大化，並提供最佳客戶體驗。您的資料只會存放在發出請求的區域，但輸入提示和輸出結果可能會在該區域之外處理。所有資料都會透過 Amazon 的安全網路進行加密傳輸。

AgentCore 中的政策會將您的推論請求安全地路由到發出請求的地理區域內的可用運算資源，如下所示：
+ 源自歐盟的推論請求將在歐盟內處理。
+ 來自美國的推論請求將在美國境內處理。
+ 來自 APAC 的推論請求將在 APAC 內處理。

**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 Gateway 和政策引擎。服務使用 AgentCore Gateway 結構描述來產生有效的 Cedar 政策。如需設定說明[，請參閱 AgentCore 中的政策入門](policy-getting-started.md)。

**注意**  
自然語言具有彈性，但精確度對於安全性至關重要。政策必須清晰明確。

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

上一節的退款政策可以自然語言表示：

 **自然語言：**

允許使用者名稱為 "refund-agent" 的委託人在退款金額低於 $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 遵循三個基本原則：
+  **根據預設，所有項目都會遭到拒絕** - 如果沒有政策明確允許 動作，則會自動封鎖
+  **禁止一律獲勝** - 如果任何禁止政策相符，即使允許政策也相符，也會拒絕存取
+  **至少需要一個許可** - 若要授予存取權，至少有一個許可政策必須相符，而且沒有任何禁止政策可以相符

 **如果預設拒絕一切，為什麼要使用禁止政策？** 

禁止政策可確保不會錯誤地允許特定動作。即使有人撰寫更廣泛的許可政策，禁止政策仍優先並封鎖存取。

 **範例案例：**

```
// 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 ...」
+ 「允許使用者名稱為 refund-agent 的使用者...」
+ 「具有角色保險代理程式的使用者可能...」
+ 「具有 refund：write 範圍的任何人都獲授權...」
+ 「所有使用者都可以...」

具體說明身分：

未完成：❌「允許處理低於 500 美元的退款」

完成：✓「允許 refund-agent 處理 500 USD 以下的退款」

### 動作規格
<a name="nl2cedar-action-specification"></a>

「什麼」會識別政策控制的操作、工具或動作。

彈性動作動詞：
+ 「允許使用者處理退款」
+ 「允許退款處理」
+ 「使用者可以建立應用程式」
+ 「授權檢視稽核日誌」

請具體說明 工具：

模糊：❌「允許使用者存取模型」

清除：✓「允許資料科學團隊存取分析模型」

### 條件規格
<a name="nl2cedar-condition-specification"></a>

「時間」指定政策適用的情況。

彈性條件式表達式：
+ "... 當金額低於 $500 時"
+ 「...如果區域是美國、加拿大或英國」
+ 「... 只有在核准狀態approved-by-manager時」
+ 「...前提是已提交風險分數」

精確說明條件：

模糊：❌「允許在金額合理時進行轉移」

精確：✓「當金額低於 10，000 美元時允許轉移」

## 政策範例
<a name="nl2cedar-policy-examples"></a>

下列範例示範如何使用明確的主體、動作和條件來建構自然語言政策。

**Topics**
+ [範例 1：簡易使用者型政策](#nl2cedar-example-1)
+ [範例 2：具有多個條件的角色型](#nl2cedar-example-2)
+ [範例 3：以範圍為基礎的存取](#nl2cedar-example-3)
+ [範例 4：具有限制條件的每個人](#nl2cedar-example-4)

### 範例 1：簡易使用者型政策
<a name="nl2cedar-example-1"></a>

當金額低於 $500 時，允許使用者 refund-agent 處理退款。

元素：
+  **對象：**使用者 refund-agent
+  **內容：**處理退款
+  **當：** 金額低於 $500

### 範例 2：具有多個條件的角色型
<a name="nl2cedar-example-2"></a>

當涵蓋範圍類型為責任或碰撞且政策為作用中時，允許具有角色保險代理的使用者更新涵蓋範圍。

元素：
+  **對象：**具有角色保險代理程式的使用者
+  **內容：**更新涵蓋範圍
+  **時機：**涵蓋範圍類型為責任或碰撞，且政策為作用中

### 範例 3：以範圍為基礎的存取
<a name="nl2cedar-example-3"></a>

當區域不是歐洲且產品符合資格時，允許具有範圍 travel：book 的使用者建立航班預訂。

元素：
+  **對象：**具有範圍 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 邏輯 （全部必須為 True)](#nl2cedar-and-logic)
+ [OR 邏輯 （至少一個必須為 True)](#nl2cedar-or-logic)
+ [複雜邏輯](#nl2cedar-complex-logic)

### AND 邏輯 （全部必須為 True)
<a name="nl2cedar-and-logic"></a>

使用字詞，例如：「和」、「也」、「額外」、「同時」、「搭配」

範例：

當區域為美國且產品符合資格且區域為作用中時，允許應用程式。

### OR 邏輯 （至少一個必須為 True)
<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>

錯誤：「允許存取退款工具」

良好：「允許使用者 refund-agent 存取退款工具」

### 錯誤 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)」