Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Questo riferimento illustra il flusso autonomo denominato-policy. Usare ARM per gestire criteri e Rego e l'endpoint del piano dati dell'account per valutarli.
Prerequisites
Completare la guida introduttiva per l'accesso in anteprima, un account di gestione e le autorizzazioni di creazione e runtime. Gli esempi di gestione usano le variabili di risorsa e gli script elencati nella guida di esempio. Eseguire gli esempi dalla directory contenente gli script di gestione.
Endpoint e versioni
| Purpose | Endpoint | Versione |
|---|---|---|
| Gestione degli account e dei criteri | https://management.azure.com |
2026-11-15-preview |
| Evaluation | Endpoint dell'account Content Safety di servizio | 2026-09-01-preview |
Le risorse dei criteri sono:
/subscriptions/{subscriptionId}/resourceGroups/{resourceGroup}
/providers/Microsoft.CognitiveServices/accounts/{accountName}
/raiRegos/{regoName}
/raiPolicies/{policyName}
Le interruzioni di riga riportate sopra sono destinate alla leggibilità. Ogni richiesta usa un singolo percorso di risorsa.
Creare rego riutilizzabile prima del criterio che vi fa riferimento. Un corpo Rego PUT contiene properties.encoding e properties.rego.
None significa fonte normale; il contratto definisce Base64anche . Negli esempi viene usata una semplice origine UTF-8.
Un corpo PUT dei criteri contiene properties.format: "ACS", properties.acse properties.acsRegos. La versione del manifesto interno è 0.4.0-alpha.1, non una delle due versioni dell'API.
Autenticazione e autorizzazione
| Call | Ambito OAuth | Accesso |
|---|---|---|
| ARM | https://management.azure.com/.default |
Azioni di gestione delle risorse necessarie per l'account e le risorse figlio. |
| Unified Moderate | https://cognitiveservices.azure.com/.default |
Cognitive Services User nell'account di gestione, con accesso in anteprima abilitato. |
| Inferenza del giudice di proprietà del cliente | Destinatari del servizio modello supportati, acquisiti dal servizio | Autorizzazione di inferenza per l'identità dell'account di gestione nell'account modello. |
Usare un endpoint di sottodominio personalizzato per l'autenticazione Microsoft Entra. Non interscambiare i token arm e del piano dati.
Il contratto del piano dati dichiara Ocp-Apim-Subscription-Key anche l'autenticazione, soggetta all'autenticazione locale e alla configurazione di anteprima dell'account. Queste guide usano le credenziali entra e consigliano le identità gestite per le applicazioni. Una chiave di sottoscrizione non è un'identità dell'applicazione separata.
Gli ID agente, i metadati degli attori, gli ID sessione e le attestazioni di identità fornite dal cliente in JSON non sono autorizzati.
Usare un'identità gestita nell'ambiente di produzione
La guida introduttiva usa un'identità per sviluppatori interattiva. Per un'applicazione, usare un'identità gestita collegata al calcolo:
- Creare o abilitare l'identità nell'host dell'applicazione.
- Concedere all'entità
Cognitive Services Userl'account content Safety per la gestione. - Configurare le credenziali dell'applicazione per selezionare l'identità e ottenere un token per
https://cognitiveservices.azure.com/.default. - Verificare che una richiesta autorizzata abbia esito positivo e che venga rifiutata un'identità non autorizzata.
Per un'identità assegnata dall'utente, le assegnazioni di ruolo usano l'ID principale e il tipo di ServicePrincipalentità . La selezione delle credenziali usa l'ID client. La creazione dell'identità senza collegarla all'host dell'applicazione non lo rende disponibile per l'applicazione.
L'identità dell'applicazione è separata dall'identità dell'account di servizio usata da un giudice LLM di proprietà del cliente.
Chiamare Unified Moderate
Questa richiesta HTTP è schema. Sostituire {endpoint} con l'endpoint dell'account Content Safety:
POST {endpoint}/contentsafety/content:unifiedModerate?api-version=2026-09-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json
Inserire policyId il corpo JSON, non la stringa di query. Usare il nome del criterio pubblicato nell'account di gestione, ad esempio refund-quickstart. Gli esempi di gestione continuano a usare gli ID ARM completi.
Per questo flusso di criteri denominati non è necessaria alcuna associazione di risorse o un selettore di risorse aggiuntivo. Non inviare sia policyId che targetResourceId.
Corpo della richiesta
In questo esempio vengono valutati gli argomenti dello strumento prima di dispatch:
{
"policyId": "refund-quickstart",
"source": "pre_tool_call",
"toolName": "refund_order",
"toolCallId": "refund-1",
"content": "{\"order_id\":\"demo-001\",\"amount\":100}",
"context": {
"agentId": "support-agent",
"sessionId": "sample-tool",
"sequence": 2
}
}
Per l'esecuzione effettiva, usare l'ID della sessione, aumentare il numero di sequenza e l'azione esatta che l'host sta per eseguire.
source |
content |
Campi degli strumenti |
|---|---|---|
input |
Testo normale nonempty. | Non inviare campi degli strumenti. |
output |
Testo normale nonempty. | Non inviare campi degli strumenti. |
pre_tool_call |
Stringa di oggetto con codifica JSON contenente gli argomenti proposti. |
toolName è obbligatorio; toolCallId è facoltativo. |
post_tool_call |
Stringa di risultato con codifica JSON; non usare JSON null. |
toolName è obbligatorio. Facoltativo: toolCallId, toolArguments (stringa di oggetto con codifica JSON), toolResultIsError (booleano) e toolDurationMs (numero finito, non negativo). |
Mantenere numeri, valori booleani, matrici, oggetti e membri Null consentiti all'interno dei valori degli strumenti con codifica JSON. Ad esempio, amount sopra è un numero dopo la contentdecodifica , non una stringa.
I campi facoltativi sono , (intero non negativo), correlationId, , tenantIduserIde extensions (stringa oggetto con codifica JSON). sequencesessionIdagentIdcontext Il servizio compila lo snapshot usato dai percorsi di destinazione del manifesto.
context Popolare con questi campi supportati.
Limits
Mantenere content e toolArguments all'interno di circa 10.000 caratteri ciascuno.
toolNameI toolCallIdcampi stringa di contesto (agentId, sessionId, correlationIduserId, e tenantId) sono limitati a 256 caratteri ciascuno. Il contesto extensions è limitato a 16 KiB di JSON UTF-8 e profondità 16.
Una dimensione supportata del payload HTTP non garantisce che un particolare classificatore o modello possa controllare tale quantità di contenuto. Le funzionalità necessarie hanno limiti di input ed esecuzione specifici.
Limiti di creazione arm
Gli artefatti dei criteri archiviati hanno limiti separati dal contesto di runtime:
| Item | Limite per gli account di anteprima abilitati | Misura |
|---|---|---|
| Manifesto ACS | 256 KiB (262.144 byte) | JSON UTF-8 serializzato compatto per properties.acs. |
| Risorsa Rego | 512 KiB (524.288 byte) | Origine UTF-8 decodificata, incluso il caricamento con encoding: "Base64". |
| Corpo ARM PUT completo | 1 MiB (1.048.576 byte) | L'intero corpo della richiesta, inclusi i wrapper JSON e l'origine codificata. |
Questi limiti dipendono dalla distribuzione in anteprima. Alcune distribuzioni applicano 48 manifesti KiB e 200 KiB decodificati Rego. Verificare i limiti abilitati per l'account prima di basarsi sui limiti più grandi.
Si applicano sia i limiti dell'artefatto che dell'intera richiesta. Base64 espande l'origine trasportata e l'escape JSON di origine normale contribuisce anche alle dimensioni del corpo. Una richiesta inferiore a 1 MiB può comunque superare il limite manifesto o rego decodificato.
Interpreta la risposta
Una risposta con esito positivo contiene:
| Membro | Meaning |
|---|---|
verdict |
allowed o blocked. |
reason |
Codice motivo facoltativo. |
content |
Contenuto originale o trasformato quando consentito; omesso quando bloccato. I valori strutturati rimangono stringhe con codifica JSON. |
acsVerdict |
Dettagli sulle decisioni: decision (allow, denyo transform), facoltativi reason, , messagewarnings, approval, transform, evidence, e harmResults. |
HTTP 200 indica che la valutazione è stata completata. Non significa che l'azione è consentita.
Ad esempio, una risposta di rifiuto include:
{
"verdict": "blocked",
"reason": "tool_request_not_permitted",
"acsVerdict": {
"decision": "deny",
"reason": "tool_request_not_permitted",
"message": "Use approved tools. Refund amounts must be numeric: >0 and <=100."
}
}
L'host deve:
- Convalidare la risposta e associarla alla richiesta esatta in sospeso.
- Arrestare i
blockeddati in formatodenynon valido o incoerente o in caso di errore operativo. - Per
allowedconallow, usare il valore valutato. Perallowedcontransform, usare e convalidare l'oggetto restituitocontent. - Eseguire o rilasciare solo il valore valutato e consentito.
- Registrare quello che è successo.
Il servizio applica già un oggetto transform. Non applicare acsVerdict.transform una seconda volta. Per input/output, l'oggetto restituito content è testo normale. Per le origini degli strumenti, analizzarlo come valore dello strumento JSON sostitutivo. Convalidare la sostituzione rispetto allo schema dell'applicazione prima dell'uso. Il percorso del giudice in queste guide non supporta verdetti di trasformazione. Se l'applicazione non è in grado di gestire in modo sicuro un flusso di lavoro di trasformazione o approvazione, mantenere bloccata l'azione.
Richieste di approvazione
Una decisione di revisione è una negazione fino a quando l'host non lo risolve. Ad esempio, questo verdetto Rego produce blocked con acsVerdict.approval.type:
{
"decision": "deny",
"reason": "human_review_required",
"approval": {
"type": "transaction-review"
}
}
Il contenuto dell'oggetto approvazione deve corrispondere a un flusso di lavoro implementato dall'applicazione; in questo esempio non ne viene effettuato il provisioning. Associare qualsiasi approvazione all'azione esatta e ai valori valutati. Non considerare la presenza di approval come autorizzazione per l'esecuzione e non consentire a un'approvazione di ignorare un rifiuto incondizionato indipendente.
Il approval campo non apre una coda di revisione o concede l'autorizzazione.
Gestire gli errori
| Stato o condizione HTTP | Action |
|---|---|
400, BadRequest |
Correggere il formato JSON non valido o un tipo di campo, ad esempio un oggetto anziché una stringa per content. |
400, InvalidRequestBody |
Correggere i campi specifici dell'origine, il selettore, il profilo non supportato o le dimensioni. Il criterio selezionato deve associare l'oggetto richiesto source. Un selettore di corpo mancante può segnalare che targetResourceId è necessario. Impostare policyId per questo flusso di criteri denominato. |
401 |
Controllare l'acquisizione delle credenziali, il gruppo di destinatari dei token e la scadenza. |
403 |
Controllare il ruolo del piano dati del chiamante selezionato, l'ambito dell'account, l'accesso in anteprima e l'autorizzazione dei criteri. |
404 |
Controllare l'abilitazione dell'endpoint, della versione dell'API, dell'account e dell'area. |
429 |
Rispettare Retry-After quando viene fornito e ridotto il carico. Mantenere bloccata l'azione. |
500, , 503errore di trasporto o timeout |
Mantenere bloccata l'azione. Riprovare solo entro una scadenza limitata dell'applicazione. |
200 con blocked / acsVerdict.decision: deny |
Un risultato dei criteri, non un errore di trasporto. Non riprovare fino a quando non diventa un consentito. |
| Verdetto non valido o incoerente | Non agire. Registrare l'errore e analizzare. |
I codici di errore operativi possono variare tra le configurazioni di gestione. Mantenere il codice restituito effettivo, lo stato HTTP e richiedere informazioni di correlazione senza registrare payload sensibili. Una funzionalità o una dipendenza non disponibile non è autorizzata a ignorarne il controllo.
Nuovi tentativi e quote
Una singola valutazione può richiamare più rilevatori o giudici obbligatori. I limiti dell'account e i limiti di distribuzione del modello sono separati; Il conteggio delle richieste HTTP di una valutazione non stabilisce il rilevamento interno o l'utilizzo dell'inferenza.
Usare le quote assegnate all'account abilitato e alla distribuzione del modello durante l'impostazione della concorrenza. Non presupporre un limite di richieste universali al secondo da questa guida.
Un nuovo tentativo di valutazione non è autorizzato a ripetere un'azione dello strumento non idempotente. Mantenere l'azione originale in sospeso, i tentativi associati in base al tempo e al conteggio e impedire l'invio duplicato. Non riutilizzare un'autorizzazione precedente per gli argomenti modificati, l'output modificato, un punto del ciclo di vita diverso o un'azione successiva.
Aggiornare e implementare i criteri
Pubblicare nuove versioni dei criteri denominate per un'implementazione a fasi. Usare la sostituzione condizionale solo quando si aggiorna intenzionalmente una risorsa esistente.
Preferisce una nuova versione denominata
Creare un nuovo criterio e una risorsa Rego con un nuovo nome, testarlo e modificare deliberatamente il selettore configurato dell'applicazione. Ad esempio, usare publish-policy.ps1:
$Candidate = .\publish-policy.ps1 -AccountId $AccountId `
-TemplateDirectory .\refund-guard -PolicyName 'refund-guard-v2'
Mantenere disponibile la versione precedente durante l'implementazione. Lo spostamento indietro del selettore è un rollback della configurazione; non annulla le azioni già eseguite.
Sostituzione sul posto condizionale
Se si sostituisce intenzionalmente un criterio, ottenere il relativo ETag corrente e usare If-Match. Nell'esempio seguente viene usato 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
Usare un corpo della richiesta accettato, non la risposta GET completa con campi di sola lettura. Un errore di precondizione richiede revisione e riconciliazione; non ripetere una sovrascrittura incondizionato.
Le modifiche apportate a Rego riutilizzabili possono influire sui criteri che vi fanno riferimento. La pubblicazione di nuove risorse denominate di origine e criteri evita di trattare gli aggiornamenti di più risorse come operazione atomica.
Le chiamate ai criteri denominati selezionano i criteri autorizzati in base al nome in policyId. Il formato di richiesta illustrato qui non aggiunge un ETag. Usare versioni denominate distinte per l'implementazione intenzionale e conservare l'ETag arm con i record di distribuzione.
Monitorare la valutazione e l'imposizione
Registrazione:
- ID di correlazione forniti da session, action, source e caller.
- Nomi di criteri configurati e ETag di distribuzione.
- Decisione e motivo, incluse le approvazioni non risolte.
- Latenza del servizio, timeout, errori e limitazione del servizio.
- Indica se l'azione è stata bloccata, inviata, trasformata o rilasciata.
Un'asserzione host utile è zero dispatch protetti o versioni dopo deny/error. Controllare anche la copertura del punto; la gestione della risposta perfetta non protegge un'azione che non ha mai chiamato il servizio.
Evitare prompt non elaborati, argomenti degli strumenti, output del modello, token di accesso e rubriche di giudice nei log di routine. I metadati di correlazione non sostituiscono un criterio di gestione dei dati.
Eliminare un criterio e il relativo rego
- Arrestare o riconfigurare i client usando i criteri.
- Verificare la presenza di altri riferimenti al rego riutilizzabile.
- Eliminare il criterio con il relativo ETag corrente.
- Se l'eliminazione è asincrona, attendere che l'operazione arm abbia esito positivo.
- Eliminare Rego solo dopo che non viene più fatto riferimento.
Per le risorse create dallo script di pubblicazione:
.\remove-policy.ps1 -PolicyId $Published.PolicyId -RegoId $Published.RegoId
Lo remove-policy.ps1 script verifica che entrambi gli ID appartengano allo stesso account, usi ETag, attenda le operazioni asincrone ed elimina solo queste due risorse. Un conflitto o un'eliminazione non riuscita è un errore; non procede forzatamente.
Lo script non elimina l'account di gestione, l'account modello, le assegnazioni di ruolo o il gruppo di risorse. Esaminare e rimuovere le risorse inutilizzate separatamente.