Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Diese Referenz behandelt den eigenständigen Fluss mit benannten Richtlinien. Verwenden Sie ARM zum Verwalten von Richtlinien und Rego sowie zum Auswerten des Datenebenenendpunkts des Kontos.
Prerequisites
Führen Sie die Schnellstartanleitung für den Vorschauzugriff, ein Dienstkonto und die Erstellungs- und Laufzeitberechtigungen aus. In den Verwaltungsbeispielen werden die Ressourcenvariablen und die im Beispielhandbuch aufgeführten Skripts verwendet. Führen Sie die Beispiele aus dem Verzeichnis aus, das die Verwaltungsskripts enthält.
Endpunkte und Versionen
| Purpose | Endpunkt | Version |
|---|---|---|
| Konto- und Richtlinienverwaltung | https://management.azure.com |
2026-11-15-preview |
| Evaluation | Der Endpunkt des dienstden Inhaltssicherheitskontos | 2026-10-15-preview |
Die Richtlinienressourcen sind:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
Die obigen Zeilenumbrüche dienen zur Lesbarkeit. Jede Anforderung verwendet einen einzelnen Ressourcenpfad.
Erstellen Sie wiederverwendbares Rego vor der Richtlinie, die darauf verweist. Ein Rego PUT-Text enthält properties.encoding und properties.rego.
None bedeutet reine Quelle; der Vertrag definiert Base64auch . In den Beispielen wird eine einfache UTF-8-Quelle verwendet.
Ein Richtlinien-PUT-Text enthält properties.format: "ACS", properties.acsund properties.acsRegos. Die innere Manifestversion ist 0.4.0-alpha.1keine API-Version.
Authentifizierung und Autorisierung
| Call | OAuth-Bereich | Access |
|---|---|---|
| ARM | https://management.azure.com/.default |
Ressourcenverwaltungsaktionen, die für das Konto und die untergeordneten Ressourcen erforderlich sind. |
| Einheitliches Mittel | https://cognitiveservices.azure.com/.default |
Cognitive Services User auf dem Dienstkonto mit aktivierter Vorschauzugriff. |
| Kundeneigene Beurteilungsverlässigkeit | Die vom Dienst erworbene unterstützte Modelldienstgruppe | Ableitungsberechtigung für die Dienstkontoidentität für das Modellkonto. |
Verwenden Sie einen benutzerdefinierten Unterdomänenendpunkt für Microsoft Entra Authentifizierung. Austausch von ARM- und Datenebenentoken nicht.
Der Vertrag für datenebene deklariert Ocp-Apim-Subscription-Key auch die Authentifizierung, vorbehaltlich der lokalen Authentifizierung und der Vorschaukonfiguration des Kontos. Diese Leitfäden verwenden Entra-Anmeldeinformationen und empfehlen verwaltete Identitäten für Anwendungen. Ein Abonnementschlüssel ist keine separate Anwendungsidentität.
Agent-IDs, Akteurmetadaten, Sitzungs-IDs und vom Kunden bereitgestellte Identitätsansprüche in JSON sind keine Autorisierung.
Verwenden einer verwalteten Identität in der Produktion
Die Schnellstartanleitung verwendet eine interaktive Entwickleridentität. Verwenden Sie für eine Anwendung eine verwaltete Identität, die an die Berechnung angefügt ist:
- Erstellen oder aktivieren Sie die Identität auf dem Anwendungshost.
- Gewähren Sie ihrem Prinzipal
Cognitive Services Userdas Dienstkonto für die Inhaltssicherheit. - Konfigurieren Sie die Anmeldeinformationen der Anwendung, um diese Identität auszuwählen und ein Token für
https://cognitiveservices.azure.com/.default. - Überprüfen Sie, ob eine autorisierte Anforderung erfolgreich ist und eine nicht autorisierte Identität abgelehnt wird.
Für eine vom Benutzer zugewiesene Identität verwenden Rollenzuweisungen die Prinzipal-ID und den Prinzipaltyp ServicePrincipal. Die Auswahl der Anmeldeinformationen verwendet die Client-ID. Das Erstellen der Identität, ohne sie an den Anwendungshost anzufügen, macht sie der Anwendung nicht zur Verfügung.
Die Identität der Anwendung unterscheidet sich von der Dienstkontoidentität, die von einem LLM-Richter im Besitz eines Kunden verwendet wird.
Einheitlichen Mäßigen anrufen
Diese HTTP-Anforderung ist schematisch.
{unified-moderate-url} enthält Ihren Endpunkt, /contentsafety/content:unifiedModerate, , api-version=2026-10-15-previewund den vollständigen ARM policyId, URL-codiert einmal.
POST {unified-moderate-url}
Authorization: Bearer <access-token>
Content-Type: application/json
Verwenden Sie die vollständige ARM-Richtlinienressourcen-ID unter dem bereitgestellten Konto als policyId. Wenn eine Bereitstellung kurze Richtliniennamen unterstützt, ist die vollständige ID immer noch die klarere Auswahl. URL-codiert es einmal mithilfe eines HTTP-Abfrage-Generators; verketten Sie keine nicht gescapeten IDs manuell.
Der eigenständige Selektor ist ein Abfrageparameter. Es ist keine Ressourcenbindung oder zusätzliche Ressourcenauswahl erforderlich.
Anforderungstext
In diesem Beispiel werden Toolargumente vor der Versendung ausgewertet:
{
"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 }
}
Verwenden Sie bei der tatsächlichen Ausführung einen aktuellen Zeitstempel, die ID Ihrer Sitzung und erhöhen sie die Sequenznummer, und die genaue Aktion, die der Host ausführen soll. Der Dienst überprüft die punktspezifische Nutzlast und die Zielgleichheit.
Behalten Sie Werte als systemeigenes JSON bei. Ein Toolargumentobjekt darf nicht als JSON-Zeichenfolge codiert werden. Bewahren Sie Zahlen, Booleane, Arrays, Objekte und NULL auf, wobei der Vertrag sie zulässt.
Die Zielzuordnung ist in Den Author-Richtlinien aufgeführt. SDK-Kontext-Generatoren helfen, diese Felder konsistent zu halten.
Limits
Anforderungen und Antworten sind jeweils auf 1.048.576 decodierte UTF-8 JSON-Bytes und Containertiefe 64 beschränkt, einschließlich des Stamms. Verwenden Sie gültige Unicode- und eindeutige JSON-Membernamen. Doppelte Member, widersprüchliche Selektoren und Übergrenzungsanforderungen sind Fehler, nicht abgeschnittene erfolgreiche Auswertungen.
Eine unterstützte HTTP-Nutzlastgröße garantiert nicht, dass ein bestimmter Klassifizierer oder -modell diese Menge von Inhalten prüfen kann. Erforderliche Funktionen verfügen über eigene Eingabe- und Ausführungsgrenzwerte.
ARM-Erstellungsgrenzwerte
Gespeicherte Richtlinienartefakte weisen separate Grenzwerte vom Laufzeitkontext auf:
| Item | Grenzwert für aktivierte Vorschaukonten | Messung |
|---|---|---|
| ACS-Manifest | 256 KiB (262.144 Bytes) | Kompakte serialisierte UTF-8 JSON für properties.acs. |
| Rego-Ressource | 512 KiB (524.288 Bytes) | Decodierte UTF-8-Quelle, einschließlich beim Hochladen mit encoding: "Base64". |
| Vollständiger ARM PUT-Textkörper | 1 MiB (1.048.576 Bytes) | Der gesamte Anforderungstext, einschließlich JSON-Wrapper und codierter Quelle. |
Diese Grenzwerte hängen von der Vorschaubereitstellung ab. Einige Bereitstellungen erzwingen 48 KiB-Manifeste und 200 KiB decodierte Rego. Bestätigen Sie die für Ihr Konto aktivierten Grenzwerte, bevor Sie sich auf die größeren Obergrenzen verlassen.
Sowohl Artefakt- als auch Ganzanforderungsgrenzwerte gelten. Base64 erweitert die transportierte Quelle, und die JSON-Entkapselung aus der Einfachen Quelle trägt ebenfalls zur Körpergröße bei. Eine Anforderung kleiner als 1 MiB kann das Manifest- oder decodierte Rego-Limit weiterhin überschreiten.
Antwort interpretieren
Eine erfolgreiche Antwort enthält:
| Mitglied | Dies bedeutet |
|---|---|
verdict |
Das Aggregat allow, denyoder transform die Entscheidung. |
receipt |
Metadaten zur Identifizierung der Auswertung und exakt ausgewerteten Anforderung und Richtlinien. |
HTTP 200 bedeutet, dass die Auswertung abgeschlossen ist. Es bedeutet nicht, dass die Aktion zulässig ist.
Beispielsweise kann das verdict Element folgendes sein:
{
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
Der Host muss:
- Überprüfen Sie die Antwort und den Beleg.
-
denyAnhalten, falsch formatierte Daten oder Betriebsfehler. - Wenden Sie eine unterstützte
transformAnwendung an, und überprüfen Sie sie, bevor Sie den Ersetzungswert verwenden. - Ausführen oder Freigeben nur des ausgewerteten, zulässigen Werts.
- Notieren Sie, was tatsächlich passiert ist.
Start- und Herunterfahren-Transformationen werden nicht unterstützt. Der Richterpfad in diesen Leitfäden unterstützt auch keine Transformationsurteile. Wenn Ihre Anwendung keinen zurückgegebenen Transformations- oder Genehmigungsworkflow sicher implementieren kann, behalten Sie die Aktion blockiert.
Genehmigungsanforderungen
Eine Überprüfungsentscheidung ist eine Ablehnung, bis Ihr Host sie aufgelöst hat. Eine Richtlinie kann beispielsweise folgendes zurückgeben:
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"workflow": "transaction-review"
}
}
Der Inhalt des Genehmigungsobjekts muss mit einem Workflow übereinstimmen, den Ihre Anwendung implementiert. In diesem Beispiel wird kein Beispiel bereitgestellt. Binden Sie alle Genehmigungen an die genauen Aktionen und ausgewerteten Werte. Behandeln Sie nicht das Vorhandensein von approval Berechtigungen für die Ausführung, und lassen Sie eine Genehmigung nicht zu, eine unabhängige bedingungslose Ablehnung außer Kraft zu setzen.
Das approval Feld öffnet keine Überprüfungswarteschlange oder gewährt keine Berechtigung.
Belegfelder
| Feld | Hostüberprüfung oder -verwendung |
|---|---|
receiptVersion |
Stimmen Sie hier mit dem Transportvertrag überein 2026-10-15-preview. |
profile |
Für diesen Fluss wird erwartet namedPolicy . |
evaluationId, attempt |
Korrelieren von Dienstauswertungs- und Hostausführungsdatensätzen. |
requestBinding |
Erforderlich algorithm: "sha256" und canonicalization: "rfc8785", dann mit dem Hash des genauen Anforderungsmaterials unten vergleichen digest . |
evaluatedPolicyLayers |
Überprüfen Sie die erwartete benannte Richtlinie; behalten Sie die Überarbeitung, den semantischen Digest, den aktivierten Artefaktdigest und die Entscheidung bei. |
evaluatedInterventionPoint |
Stimmen Sie mit dem in dieser Anforderung gesendeten Punkt überein. |
requiredInterventionPoints |
Überprüfen Sie, ob Ihr Host jeden erforderlichen Punkt implementiert. Dies beweist nicht, dass der Host sie aufgerufen hat. |
hostProfileVersion |
Notieren Sie das Dienstauswertungsprofil. |
authenticatedProducerResourceId |
Stimmen Sie für diesen namedPolicy Fluss mit der Dienstkonto-ID aus der vertrauenswürdigen Konfiguration überein, nicht mit einem Wert, der aus der Antwort kopiert wurde. |
harmResults, wenn vorhanden |
Öffentliche Klassifiziererzusammenfassungen, nicht die Rego-Eingabe oder vollständige interne Modelldiagnose. |
Beispielsweise hat eine vollständige Antwort mit der Bezeichnungsrichtlinie dieses Shape. Die Ressourcen-IDs, Revisions-, Auswertungs-ID und Digests sind illustrative Platzhalter und keine Werte, die in einen Validator kopiert werden sollen. Reale policyResourceId und authenticatedProducerResourceId Werte sind vollständige ARM-IDs für die Richtlinie bzw. das Dienstkonto:
{
"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>"
}
}
Jeder reale Digest enthält sha256: gefolgt von 64 Hexadezimalzeichen in Kleinbuchstaben.
evaluatedPolicyLayers kann zusätzliche anwendbare Ebenen enthalten; gehen Sie nicht davon aus, dass immer genau eins vorhanden ist. Überprüfen Sie, ob die ausgewählte benannte Richtlinie vorhanden ist, behalten Sie die anderen Ebenen bei, und erzwingen Sie die Aggregatbewertung anstelle der Zulässigkeit einer einzelnen Ebene.
Der Anforderungsbindungsdigest ist der SHA-256-Hash von RFC 8785 (kanonischer UTF-8-JSON)-Code für:
{
"apiVersion": <the exact Unified Moderate API version>,
"context": <the exact decoded request body>,
"selectors": { "policyId": <the exact accepted selector value> }
}
Der Digestzeichenfolge wird ein Präfix vorangestellt sha256:. Verwenden Sie eine Kanonisierungsbibliothek, anstatt davon auszugehen, dass die normale JSON-Serialisierung die erforderliche Reihenfolge und Zahlendarstellung aufweist. Der Beispielclient implementiert diese Überprüfung.
Der Digest bindet Auswertungsmetadaten an eine Anforderung; Es handelt sich nicht um eine Bestätigungssignatur oder einen Nachweis, dass ein Tool ausgeführt wurde. Behalten Sie dies mit einem separaten Hostergebnis bei.
Fehler behandeln
| HTTP-Status oder -Bedingung | Action |
|---|---|
400, InvalidRequest |
Korrigieren Sie den Kontext, JSON-Typen, Punkt-/Zielpaarung, Selektor oder Nutzlastgröße. |
401 |
Überprüfen Sie den Erwerb von Anmeldeinformationen, die Tokengruppe und den Ablauf. |
403 |
Überprüfen Sie die Datenebenenrolle, den Kontobereich, den Vorschauzugriff und die Richtlinienautorisierung des ausgewählten Anrufers. |
404, NativeRouteDisabled |
Überprüfen Sie die Endpunkt-, API-Version, Konto- und Regionsaktivierung. Ändern Sie sich nicht als automatisches Ausweichen in ein älteres Anforderungsformat. |
409, PolicyFenceChanged |
Die Richtlinie wurde während der Auswertung geändert. Stimmen Sie die beabsichtigte Version ab, bevor ein gebundener Wiederholungsversuche wiederholt wird. |
UnsupportedCapability oder nicht verfügbar erforderliche Richtlinie/Abhängigkeit |
Stellen Sie die erforderliche Funktion oder Richtlinie wieder her. Überspringen Sie die Überprüfung nicht. |
429 |
Honor Retry-After when supplied and reduce load. Halten Sie die Aktion blockiert. |
500, 503Transportfehler oder Timeout |
Halten Sie die Aktion blockiert. Wiederholen Sie den Vorgang nur innerhalb einer begrenzten Bewerbungsfrist. |
200 mit deny |
Ein Richtlinienergebnis, kein Transportfehler. Versuchen Sie es erst erneut, wenn sie zu einer Zulassung wird. |
| Ungültige Übereinstimmung zwischen Bewertung oder Bestätigung | Handeln Sie nicht. Notieren Sie den Fehler, und untersuchen Sie es. |
Betriebsfehlercodes können sich zwischen den Bereitstellungskonfigurationen unterscheiden. Bewahren Sie den tatsächlich zurückgegebenen Code, den HTTP-Status und die Korrelationsinformationen zur Anforderung/Auswertung auf, ohne vertrauliche Nutzlasten zu protokollieren.
Wiederholungen und Kontingente
Eine einzelne Auswertung kann mehrere erforderliche Detektoren oder Richter aufrufen. Kontobeschränkungen und Modellbereitstellungsgrenzwerte sind getrennt; Die ANZAHL der HTTP-Anforderungen einer Auswertung richtet nicht den internen Detektor oder die Ableitungsverwendung ein.
Verwenden Sie beim Festlegen der Parallelität die Kontingente, die Ihrem aktivierten Konto und Ihrer Modellbereitstellung zugewiesen sind. Gehen Sie nicht von einem universellen Grenzwert für Anforderungen pro Sekunde aus diesem Leitfaden aus.
Ein Auswertungs-Wiederholungsversuche ist nicht berechtigt, eine nicht-idempotente Toolaktion erneut zu versuchen. Halten Sie die ursprüngliche Aktion aus, gebundene Wiederholungen nach Zeit und Anzahl, und verhindern Sie den doppelten Versand. Verwenden Sie keine vorherige Zulassung für geänderte Argumente, geänderte Ausgabe, einen anderen Lebenszykluspunkt oder eine spätere Aktion.
Aktualisieren und Bereitstellen von Richtlinien
Veröffentlichen Sie neue benannte Richtlinienversionen für ein mehrstufiges Rollout. Verwenden Sie bedingten Ersatz nur, wenn Sie eine vorhandene Ressource absichtlich aktualisieren.
Bevorzugen einer neuen benannten Version
Erstellen Sie eine neue Richtlinie und eine Rego-Ressource mit einem neuen Namen, testen Sie sie, und ändern Sie absichtlich die konfigurierte Auswahl der Anwendung. Verwenden Sie z. B. Folgendes publish-policy.ps1:
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
Halten Sie die vorherige Version während des Rollouts zur Verfügung. Das Verschieben der Auswahl zurück ist ein Konfigurationsrollback; Es werden keine bereits ausgeführten Aktionen rückgängig gemacht.
Bedingte Direkte Ersetzung
Wenn Sie eine Richtlinie absichtlich ersetzen, rufen Sie das aktuelle ETag ab, und verwenden Sie If-Matches. Im folgenden Beispiel wird arm.ps1 verwendet:
. .\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
Verwenden Sie einen akzeptierten Anforderungstext, nicht die vollständige GET-Antwort mit schreibgeschützten Feldern. Ein Vorbedingungsfehler erfordert Überprüfung und Abstimmung; Versuchen Sie nicht erneut, eine bedingungslose Überschreibung auszuführen.
Änderungen an wiederverwendbaren Rego können sich auf Richtlinien auswirken, die darauf verweisen. Das Veröffentlichen neuer benannter Quell- und Richtlinienressourcen vermeidet die Behandlung von Aktualisierungen mit mehreren Ressourcen als Atomoperation.
Benannte Richtlinienaufrufe wählen die autorisierte Richtlinie nach ID aus; Das hier gezeigte Anforderungsformat hefte kein ETag an. Verwenden Sie unterschiedliche benannte Versionen für den absichtlichen Rollout, und notieren Sie die tatsächliche Überarbeitung, die in jedem Beleg zurückgegeben wird.
Überwachen der Auswertung und Durchsetzung
Aufzeichnung:
- Sitzungs-, Aktions-, Punkt- und Auswertungs-IDs.
- Richtlinienressourcen-IDs, Überarbeitungen und Digests.
- Entscheidung und Grund, einschließlich nicht aufgelöster Genehmigungen.
- Dienstlatenz, Timeouts, Fehler und Drosselung.
- Gibt an, ob die Aktion blockiert, verteilt, transformiert oder freigegeben wurde.
Eine nützliche Host assertion ist zero protected dispatches or releases after deny/error. Überprüfen Sie auch die Punktabdeckung; Die perfekte Reaktionsbehandlung schützt keine Aktion, die nie den Dienst aufgerufen hat.
Vermeiden Sie unformatierte Eingabeaufforderungen, Toolargumente, Modellausgabe, Zugriffstoken und bewerten Sie Rubriken in Routineprotokollen. Belegmetadaten sind für die Korrelation nützlich, ersetzen aber keine Datenverarbeitungsrichtlinie.
Löschen einer Richtlinie und des zugehörigen Regos
- Beenden oder neu konfigurieren Clients mithilfe der Richtlinie.
- Überprüfen Sie auf andere Verweise auf ihr wiederverwendbares Rego.
- Löschen Sie die Richtlinie mit dem aktuellen ETag.
- Wenn das Löschen asynchron ist, warten Sie, bis der ARM-Vorgang erfolgreich ist.
- Löschen Sie Rego nur, nachdem sie nicht mehr referenziert wurde.
Für Ressourcen, die vom Veröffentlichungsskript erstellt wurden:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
Das remove-policy.ps1 Skript überprüft, ob beide IDs zum gleichen Konto gehören, verwendet ETags, wartet auf asynchrone Vorgänge und löscht nur diese beiden Ressourcen. Ein Konflikt oder fehler beim Löschen ist ein Fehler; sie wird nicht erzwungen.
Das Skript löscht das Dienstkonto, das Modellkonto, die Rollenzuweisungen oder die Ressourcengruppe nicht. Überprüfen und entfernen Sie nicht verwendete Ressourcen separat.