本參考文獻涵蓋獨立命名政策流程。 使用 ARM 管理政策與 Rego,並透過帳戶的資料平面端點來評估它們。
Prerequisites
完成 快速入門 程序以取得預覽權限、服務帳戶,以及撰寫與執行權限。 管理範例使用其資源變數及 範例指南中列出的腳本。 從包含管理腳本的目錄執行範例。
端點與版本
| Purpose | Endpoint | 版本 |
|---|---|---|
| 帳戶與政策管理 | https://management.azure.com |
2026-11-15-preview |
| Evaluation | 提供內容安全帳戶的端點 | 2026-10-15-preview |
政策資源包括:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
上方的換行是為了讓讀者更易讀。 每個請求使用單一資源路徑。
在引用該 Rego 的政策之前建立可重複使用的 Rego。 Rego PUT 體包含 properties.encoding 和 properties.rego。
None 意指純源;契約也定義 Base64了 。 範例中使用純 UTF-8 原始碼。
政策 PUT 主體包含 properties.format: "ACS"、 、 properties.acsproperties.acsRegos及 。 內部清單版本為 0.4.0-alpha.1,而非任一 API 版本。
身份驗證與授權
| Call | OAuth 範圍 | 存取 |
|---|---|---|
| ARM | https://management.azure.com/.default |
帳戶及子資源所需的資源管理操作。 |
| 統一溫和黨 | https://cognitiveservices.azure.com/.default |
Cognitive Services User 在服務帳戶上,並啟用預覽存取。 |
| 客戶擁有的法官推論 | 服務所取得的支援模型服務受眾 | 模型帳戶上提供提供服務帳戶身份的推論權限。 |
使用自訂子網域端點進行 Microsoft Entra 驗證。 請勿互換 ARM 與資料平面標記。
資料平面合約也會宣 Ocp-Apim-Subscription-Key 告驗證,但須依帳戶的本地驗證與預覽設定而定。 這些指南使用 Entra 憑證,並建議應用程式使用受管理身份。 訂閱金鑰並非獨立的應用程式識別碼。
代理程式 ID、演員元資料、工作階段 ID 以及客戶提供的 JSON 身份聲明不屬於授權。
在生產環境中使用受管理身份
快速啟動使用互動式開發者身份。 對於應用程式,請使用附加在其運算上的受管理身份:
- 在應用程式主機上建立或啟用該身份。
- 將其本金
Cognitive Services User用於服務內容安全帳戶。 - 設定應用程式的認證以選擇該身份並取得
https://cognitiveservices.azure.com/.default。 - 確認授權請求是否成功,且未授權的身份是否被拒絕。
對於使用者指派的身份,角色指派會使用其 主體 ID 與主體類型 ServicePrincipal。 憑證選擇使用其 用戶端 ID。 建立身份但未將其附加至應用程式主機,並不會讓該應用程式可用。
該應用程式的身份與客戶擁有的 LLM 評審所使用的服務帳戶身份是分開的。
呼叫統一 中等
此 HTTP 請求為示意圖。
{unified-moderate-url} 包含您的端點、 /contentsafety/content:unifiedModerate、 api-version=2026-10-15-preview、以及完整的 ARM policyId,並以一次 URL 編碼。
POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json
在服務帳戶下使用完整的 ARM 政策資源 ID,作為 policyId。 當部署支援簡短的政策名稱時,完整 ID 仍然是較清晰的選擇器。 使用 HTTP 查詢建構器對其進行一次 URL 編碼;請勿手動串接未跳義的 ID。
獨立選擇器是一個查詢參數。 不需要資源綁定或額外的資源選擇器。
要求本文
此範例在派遣前評估工具參數:
{
"spec": "agent-hooks/0.1",
"interception_point": "pre_tool_call",
"timestamp": "2026-11-04T12:00:00Z",
"sequence": 2,
"agent": { "id": "support-agent", "framework": "custom" },
"session": { "id": "sample-tool" },
"tool_call": {
"id": "refund-1",
"name": "refund_order",
"args": { "order_id": "demo-001", "amount": 100 }
},
"target": { "order_id": "demo-001", "amount": 100 }
}
實際執行時,請使用目前的時間戳記、您的工作階段 ID 與遞增序號,以及主機即將執行的精確動作。 該服務會驗證特定點的有效載荷與目標的一致性。
保持值為原生 JSON。 工具參數物件不得以 JSON 字串編碼。 在合約允許時保留數字、布林值、陣列、物件與 null。
目標對應會列在 作者政策中。 SDK 上下文建構器有助於維持這些欄位的一致性。
Limits
請求與回應各自限制為 1,048,576 個解碼後的 UTF-8 JSON 位元組 ,以及 容器深度 64,包括根節點。 使用有效的 Unicode 及明確的 JSON 成員名稱。 重複成員、選擇器衝突及超限請求屬於錯誤,而非截斷的成功評估。
支援的 HTTP 有效載荷大小並不保證特定分類器或模型能檢查該數量的內容。 所需功能有其自身的輸入與執行限制。
ARM 著作限制
儲存的政策產物與執行時上下文有不同的限制:
| Item | 啟用預覽帳戶的限制 | 測量 |
|---|---|---|
| ACS 清單 | 256 KiB (262,144 位元節) | 精簡序列化的 UTF-8 JSON 用於 properties.acs。 |
| Rego 資源 | 512 KiB (524,288 位元組) | 解碼 UTF-8 原始碼,包括上傳時。encoding: "Base64" |
| 完整 ARM PUT 車身 | 1 MiB (1,048,576 位元組) | 整個請求主體,包括 JSON 封裝器與編碼原始碼。 |
這些限制取決於預覽部署。 部分部署強制執行 48 KiB 清單及 200 KiB 解碼 Rego。 在依賴較大上限之前,請先確認你的帳戶已啟用的限制。
工件限制與整件請求限制同時適用。 Base64 會擴展傳輸的原始碼,而純原始碼 JSON 轉義也會增加主體大小。 小於 1 MiB 的請求仍可能超過清單或解碼後的 Rego 限制。
解讀回應
成功回應包括:
| 會員 | Meaning |
|---|---|
verdict |
總體 allow、 deny或 transform 決定。 |
receipt |
描述評估內容、精確評估請求與政策的元資料。 |
HTTP 200 表示評估已完成。 這並不代表該行動是被允許的。
例如, verdict 成員可以是:
{
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
主持人必須:
- 驗證回應與收件。
- 停止、
deny資料格式錯誤或操作失敗。 - 在使用替換值之前,請套用並驗證支援
transform值。 - 只執行或釋放已評估且允許的值。
- 記錄實際發生了什麼。
啟動與關機轉換不支援。 這些指南中的法官路線也不支援轉換判決。 如果您的應用程式無法安全地實作回傳的轉換或核准工作流程,請將該動作封鎖。
核准申請
審查決定在房東解決之前即為拒絕。 政策可以回傳,例如:
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"workflow": "transaction-review"
}
}
核准物件的內容必須與您的應用程式實作的工作流程相符;此範例未提供此選項。 將任何核准綁定於具體行動及評估後的數值。 不要把 的 approval 存在視為執行許可,也不要讓核准凌駕於獨立且無條件的拒絕之上。
此 approval 欄位不會開啟審核佇列或授予權限。
收據欄位
| Field | 主機檢查或使用 |
|---|---|
receiptVersion |
在這裡匹配運輸合約 2026-10-15-preview。 |
profile |
請期待 namedPolicy 這樣的流程。 |
evaluationId,attempt |
關聯服務評估與主機執行紀錄。 |
requestBinding |
要求 algorithm: "sha256" 和 canonicalization: "rfc8785",然後與下方請求材料的雜湊值進行比較 digest 。 |
evaluatedPolicyLayers |
驗證預期的命名政策;保留其修訂版、語意摘要、啟動化產物摘要與決策。 |
evaluatedInterventionPoint |
請與此請求中所送的重點相符。 |
requiredInterventionPoints |
檢查你的主機是否實現了所有必要的點。 這並不能證明是主持人打電話給他們。 |
hostProfileVersion |
記錄服務評估設定檔。 |
authenticatedProducerResourceId |
在此 namedPolicy 流程中,請匹配受信任設定中的服務帳戶 ID,而非從回應中複製的值。 |
harmResults,存在時 |
公開分類器摘要,而非 Rego 輸入或完整的內部模型診斷。 |
例如,完整命名政策拒絕回應的形狀如下。 資源 ID、修訂版、評估 ID 和摘要只是示範性占位符,不是要複製到驗證器的值。 實數 policyResourceId 與 authenticatedProducerResourceId 值分別為保單帳戶與服務帳戶的完整 ARM ID:
{
"verdict": { "decision": "deny", "reason": "refund_not_permitted" },
"receipt": {
"receiptVersion": "2026-10-15-preview",
"profile": "namedPolicy",
"evaluationId": "evaluation-<unique-id>",
"attempt": 1,
"requestBinding": {
"algorithm": "sha256",
"canonicalization": "rfc8785",
"digest": "sha256:<request-digest>"
},
"evaluatedPolicyLayers": [
{
"kind": "namedPolicy",
"policyResourceId": "<full-policy-resource-id>",
"policyRevision": "<policy-revision>",
"policySemanticDigest": "sha256:<semantic-digest>",
"manifestRegoDigest": "sha256:<artifact-digest>",
"decision": "deny"
}
],
"evaluatedInterventionPoint": "pre_tool_call",
"requiredInterventionPoints": ["pre_tool_call"],
"hostProfileVersion": "<host-profile-version>",
"authenticatedProducerResourceId": "<serving-account-resource-id>"
}
}
每個真實摘要後面接 sha256: 著 64 個小寫十六進位字元。
evaluatedPolicyLayers 可以包含額外的適用圖層;不要假設總是有恰好一個。 確認所選命名政策是否存在,保留其他層,並強制執行彙總判定而非單一層的允許。
請求綁定摘要是 RFC 8785 標準 UTF-8 JSON 的 SHA-256 雜湊值,適用於:
{
"apiVersion": <the exact Unified Moderate API version>,
"context": <the exact decoded request body>,
"selectors": { "policyId": <the exact accepted selector value> }
}
摘要字串前綴 sha256:。 使用典範化函式庫,而非假設一般 JSON 序列化已具備所需的順序與編號表示。 範例用戶端實作了此檢查。
摘要會將評估元資料綁定到請求中;它不是收據簽名,也不是工具執行的證明。 保留一個獨立的宿主結果。
處理錯誤
| HTTP 狀態或條件 | Action |
|---|---|
400,InvalidRequest |
修正上下文、JSON 類型、點/目標配對、選擇器或有效載荷大小。 |
401 |
檢查憑證取得、令牌受眾及到期時間。 |
403 |
檢查所選呼叫者的資料平面角色、帳戶範圍、預覽存取權及政策授權。 |
404,NativeRouteDisabled |
檢查端點、API 版本、帳戶及區域啟用情況。 請勿將舊請求格式自動切換為備援。 |
409,PolicyFenceChanged |
評估期間政策有所改變。 在進行有界重試前,先調和預期版本。 |
UnsupportedCapability 或不可用的必要政策/依賴 |
還原所需的功能或政策。 不要跳過檢查。 |
429 |
供應時就尊重 Retry-After ,減輕負荷。 保持動作被阻擋。 |
500、、 503傳輸錯誤或逾時 |
保持動作被阻擋。 僅在有限制的申請截止日前重試。 |
200 和 deny |
這是政策上的結果,而非運輸失敗。 在它變成許可之前不要重試。 |
| 判決無效或收據不符 | 不要行動。記錄失敗並進行調查。 |
操作錯誤代碼可能因服務配置而異。 保留實際回傳的程式碼、HTTP 狀態以及請求/評估相關資訊,而不記錄敏感的有效載荷。
重試與配額
單一評估可能觸發多個必要的偵測器或法官。 帳戶限制與模型部署限制是分開的;評估的 HTTP 請求次數並不能確定其內部偵測器或推論的使用情況。
設定並發時,請使用您已啟用帳戶及模型部署所指派的配額。 請勿根據本指南假設所有的每秒請求數限制。
評估重試並不等於允許重試非冪等工具動作。 保持原始動作待處理狀態,重試時間與計數綁定,並防止重複派遣。 不要重複使用先前允許變更參數、變更輸出、不同的生命週期點或後續動作。
更新並推出政策
發佈新的命名政策版本以進行分階段部署。 僅在您有意更新現有資源時使用條件式替換。
偏好新命名版本
建立一個新的政策與 Rego 資源,並以新名稱進行測試,並刻意更改應用程式已設定的選擇器。 例如,請使用 publish-policy.ps1:
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
在推出時保留先前版本。 將選擇器往後移就是設定回滾;它不會撤銷已執行的動作。
條件式原位替換
如果你有意替換某個保單,請取得其目前的 ETag 並使用 If-Match。 下列範例會使用 arm.ps1:
. .\arm.ps1
$Current = Invoke-AgentControlArm -Method GET -ResourceId $PolicyId
if (-not $Current.ETag) { throw 'The current policy has no ETag.' }
$Replacement = Get-Content .\refund-guard\policy.json -Raw |
ConvertFrom-Json -AsHashtable
# Preserve or deliberately change the same-account Rego references.
$Replacement.properties.acsRegos[0].regoName = '<intended-existing-Rego-name>'
$Updated = Invoke-AgentControlArm -Method PUT -ResourceId $PolicyId `
-Headers @{ 'If-Match' = $Current.ETag } -Body $Replacement
請使用已接受的請求主體,而非完整的 GET 回應且只提供唯讀欄位。 先決條件失敗需要審查與對帳;請勿重試無條件覆寫。
對可重複使用 Rego 的變更可能會影響相關政策。 發佈新的命名來源與政策資源,避免將多資源更新視為原子操作。
命名政策通話依 ID 選擇授權政策;此處顯示的請求格式並未釘選 ETag。 在有意識的推出時,使用不同的命名版本,並在每張收據中記錄實際回傳的修訂內容。
監控評估與執行情況
紀錄:
- Session、Action、Point 與 Evaluation ID。
- 政策資源 ID、修訂版與摘要。
- 決定與理由,包括未解決的核准。
- 服務延遲、逾時、故障與節流。
- 動作是被阻擋、派遣、轉換或釋放。
一個有用的主機斷言是在 拒絕/錯誤後,零受保護的派遣或釋放。 檢查點的覆蓋範圍也包括;完美回應處理無法保護從未呼叫服務的動作。
避免使用原始提示、工具參數、模型輸出、存取權杖,並在例行日誌中判斷評分標準。 收據元資料有助於關聯,但無法取代資料處理政策。
刪除政策及其 Rego
- 使用政策停止或重新設定用戶端。
- 查查其他關於它可重複使用的 Rego 的參考資料。
- 刪除帶有目前 ETag 的政策。
- 如果刪除是非同步的,請等待 ARM 操作成功。
- 只有在不再被引用後才刪除 Rego。
對於由發佈腳本建立的資源:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
腳本會 remove-policy.ps1 檢查兩個 ID 是否屬於同一帳戶,使用 ETag,等待非同步操作,並只刪除這兩個資源。 衝突或刪除失敗即為錯誤;它並非以武力推動。
此指令碼不會刪除服務帳戶、模型帳戶、角色指派或資源群組。 請分別檢視並移除未使用的資源。