Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Эта ссылка охватывает автономный поток именованных политик. Используйте ARM для управления политиками и Rego, а также конечной точкой плоскости данных учетной записи для их оценки.
Prerequisites
Выполните краткое руководство по предварительной версии доступа, учетной записи обслуживания и разрешениям на разработку и среду выполнения. Примеры управления используют переменные ресурсов и скрипты, перечисленные в примере руководства. Запустите примеры из каталога, содержащего скрипты управления.
Конечные точки и версии
| Purpose | Конечная точка | Версия |
|---|---|---|
| Управление учетными записями и политиками | 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 PUT содержит properties.encoding и properties.rego.
None означает обычный источник; Контракт также определяет Base64. В примерах используется обычный источник UTF-8.
Текст PUT политики содержит properties.format: "ACS"и properties.acsproperties.acsRegos. Внутренняя версия манифеста — 0.4.0-alpha.1это не версия API.
Проверка подлинности и авторизация
| Call | Область OAuth | Access |
|---|---|---|
| ARM | https://management.azure.com/.default |
Действия по управлению ресурсами, необходимые для учетных записей и дочерних ресурсов. |
| Унифицированный умеренный | https://cognitiveservices.azure.com/.default |
Cognitive Services User в учетной записи обслуживания с включенным предварительным доступом. |
| Вывод судьи, принадлежащий клиенту | Поддерживаемая аудитория службы моделей, приобретенная службой. | Разрешение на вывод для удостоверения учетной записи обслуживания в учетной записи модели. |
Используйте конечную точку пользовательского поддомена для проверки подлинности Microsoft Entra. Не обменяйтесь маркерами ARM и плоскости данных.
Контракт плоскости данных также объявляет Ocp-Apim-Subscription-Key проверку подлинности, при условии локальной проверки подлинности и предварительной версии учетной записи. В этих руководствах используются учетные данные Entra и рекомендуются управляемые удостоверения для приложений. Ключ подписки не является отдельным удостоверением приложения.
Идентификаторы агента, метаданные субъекта, идентификаторы сеансов и утверждения удостоверения, предоставленные клиентом в JSON, не являются авторизацией.
Использование управляемого удостоверения в рабочей среде
В кратком руководстве используется интерактивное удостоверение разработчика. Для приложения используйте управляемое удостоверение, подключенное к вычислительным ресурсам:
- Создайте или включите удостоверение на узле приложения.
- Предоставьте субъекту
Cognitive Services Userотлужебную учетную запись безопасности содержимого. - Настройте учетные данные приложения, чтобы выбрать это удостоверение и получить маркер для
https://cognitiveservices.azure.com/.default. - Убедитесь, что авторизованный запрос успешно выполнен, и несанкционированное удостоверение отклонено.
Для удостоверения, назначаемого пользователем, назначения ролей используют свой идентификатор субъекта и тип ServicePrincipalсубъекта. Выбор учетных данных использует свой идентификатор клиента. Создание удостоверения без его подключения к узлу приложения не делает его доступным для приложения.
Удостоверение приложения отличается от удостоверения учетной записи обслуживания, используемой судьей LLM, принадлежащей клиенту.
Вызов единого модерации
Этот HTTP-запрос является схематичным.
{unified-moderate-url}включает конечную точку, /contentsafety/content:unifiedModerateapi-version=2026-10-15-previewи полную кодировку ARMpolicyId, закодированную один раз.
POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json
Используйте полный идентификатор ресурса политики ARM в качестве учетной записи policyIdобслуживания. Если развертывание поддерживает короткие имена политик, полный идентификатор по-прежнему является более четким селектором. URL-кодирование после использования построителя HTTP-запросов; не сцепляйте идентификаторы без ввода вручную.
Автономный селектор — это параметр запроса. Привязка ресурсов или дополнительный селектор ресурсов не требуется.
Текст запроса
В этом примере вычисляется аргументы инструментов перед отправкой:
{
"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 }
}
Для фактического выполнения используйте текущую метку времени, идентификатор сеанса и увеличение порядкового номера, а также точное действие, выполняемое узлом. Служба проверяет полезные данные для конкретных точек и целевое равенство.
Сохраняйте значения как собственные JSON. Объект аргумента инструмента не должен быть закодирован как строка JSON. Сохраняйте числа, логические элементы, массивы, объекты и null, где контракт разрешает их.
Целевое сопоставление отображается в политиках author. Конструкторы контекстов ПАКЕТА SDK помогают обеспечить согласованность этих полей.
Limits
Запросы и ответы ограничены 1048 576 декодированных байтами JSON UTF-8 и глубиной контейнера 64, включая корневой. Используйте допустимые имена членов Юникода и однозначные имена элементов JSON. Повторяющиеся члены, конфликтующие селекторы и запросы чрезмерного ограничения — это ошибки, а не усеченные успешные оценки.
Поддерживаемый размер полезных данных HTTP не гарантирует, что определенный классификатор или модель может проверить этот объем содержимого. Необходимые возможности имеют собственные ограничения ввода и выполнения.
Ограничения разработки ARM
Сохраненные артефакты политики имеют отдельные ограничения от контекста среды выполнения:
| Item | Ограничение на включенные учетные записи предварительной версии | Измерение |
|---|---|---|
| Манифест ACS | 256 КиБ (262 144 байта) | Компактный сериализованный json UTF-8 для properties.acs. |
| Ресурс Rego | 512 КиБ (524 288 байт) | Декодирован источник UTF-8, в том числе при отправке с encoding: "Base64"помощью . |
| Полный текст ARM PUT | 1 MiB (1 048 576 байт) | Весь текст запроса, включая оболочки JSON и закодированный источник. |
Эти ограничения зависят от развертывания предварительной версии. Некоторые развертывания применяют 48 манифестов KiB и 200 КиБ декодированных Rego. Подтвердите ограничения, включенные для учетной записи, прежде чем полагаться на более крупные ограничения.
Применяются как артефакты, так и ограничения всего запроса. Base64 расширяет транспортированную исходную папку и экранирование JSON с открытым исходным кодом также способствует размеру тела. Запрос меньше 1 МиБ по-прежнему может превышать манифест или декодировано ограничение Rego.
Интерпретируйте ответ
Успешный ответ содержит следующее:
| Член | Meaning |
|---|---|
verdict |
Агрегат allowили denytransform решение. |
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 потока соответствует идентификатор учетной записи обслуживания из доверенной конфигурации, а не значение, скопированное из ответа. |
harmResults, когда присутствует |
Общие сводки классификатора, а не входные данные Rego или полная внутренняя диагностика модели. |
Например, полный ответ запрета именованной политики имеет эту фигуру. Идентификаторы ресурсов, редакция, идентификатор оценки и дайджесты являются иллюстрированными заполнителями, а не значениями для копирования в проверяющий элемент. Реальные policyResourceId и authenticatedProducerResourceId значения являются полными идентификаторами ARM для политики и учетной записи обслуживания соответственно:
{
"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 может содержать дополнительные применимые слои; Не предполагайте, что всегда есть именно один. Проверьте наличие выбранной именованной политики, сохраните другие слои и примените агрегированный вердикт, а не разрешить отдельный слой.
Дайджест привязки запроса — это хэш SHA-256 канонического RFC 8785 UTF-8 JSON для:
{
"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 могут повлиять на политики, ссылающиеся на него. Публикация новых именованных ресурсов источника и политики позволяет избежать обработки обновлений с несколькими ресурсами как атомарной операции.
Вызовы именованной политики выбирают авторизованную политику по идентификатору; Формат запроса, показанный здесь, не закрепляет ETag. Используйте отдельные именованные версии для преднамеренного развертывания и запишите фактическую редакцию, возвращенную в каждой квитанции.
Мониторинг оценки и принудительного применения
Записи:
- Идентификаторы сеанса, действия, точки и оценки.
- Идентификаторы ресурсов политики, редакции и дайджесты.
- Решение и причина, включая неразрешенные утверждения.
- Задержка службы, время ожидания, сбои и регулирование.
- Будет ли действие заблокировано, отправлено, преобразовано или выпущено.
Полезное утверждение узла равно нулю защищенным диспетчерам или выпускам после запрета или ошибки. Кроме того, покрытие контрольной точки; Идеальная обработка ответов не защищает действие, которое никогда не вызывало службу.
Избегайте необработанных запросов, аргументов инструментов, выходных данных модели, маркеров доступа и рубрик судьи в журналах подпрограмм. Метаданные квитанции полезны для корреляции, но она не заменяет политику обработки данных.
Удаление политики и его rego
- Остановите или перенастроите клиенты с помощью политики.
- Проверьте наличие других ссылок на его повторно используемый Rego.
- Удалите политику с текущим ETag.
- Если удаление является асинхронным, дождитесь успешной операции ARM.
- Удалить Rego только после того, как он больше не ссылается.
Для ресурсов, созданных скриптом публикации:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
Сценарий remove-policy.ps1 проверяет, принадлежат ли оба идентификатора к одной учетной записи, используют ETags, ожидает асинхронных операций и удаляет только эти два ресурса. Конфликт или сбой удаления является ошибкой; он не продолжается силой.
Скрипт не удаляет учетную запись обслуживания, учетную запись модели, назначения ролей или группу ресурсов. Просмотрите и удалите неиспользуемые ресурсы отдельно.