Informazioni di riferimento sulle funzioni dei criteri di servizio

Important

Questa funzionalità è in versione beta. Gli amministratori dello spazio di lavoro possono controllare l'accesso a questa funzione dalla pagina delle anteprime scegliendo l'anteprima delle Unity Ai Gateway Service Policys. Vedere Gestire le anteprime a livello di area di lavoro.

Una policy di servizio SQL personalizzata è una funzione SQL definita dall'utente (UDF) registrata nel Catalogo Unity che Azure Databricks valuta ad ogni interazione con il servizio a cui è collegata. Questa pagina è il campo e le informazioni di riferimento sulla sintassi per tali funzioni. Per la procedura end-to-end, vedi Crea una policy SQL.

Firma della funzione

Una funzione dei criteri di servizio accetta un singolo eventVARIANT parametro e restituisce :VARIANT

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

La funzione viene eseguita in entrambi i punti di valutazione. Branch on event:type::string per distinguerli:

  • 'request': la fase di input (ON CALL), prima che il servizio venga invocato.
  • 'response': la fase di output (ON RESULT), dopo che il servizio risponde.

Argomento event

event contiene i dati di interazione e il contesto. I campi disponibili dipendono dal tipo di servizio:

Campo Si applica a Descrizione
event:type Tutti i servizi La fase: 'request' (input, IN CHIAMATA) oppure 'response' (output, ON RESULT).
event:target Tutti i servizi Il nome completo del catalogo unity del servizio a cui è associato il criterio (facoltativo).
event:context.request_tags Servizi Modello, Servizi Fornitori Modello, Servizi MCP (tools/call) Un oggetto JSON di chiavi di stringa fornite dal chiamante e valori di stringa. Vedi Tag Richiesta.
event:context.actor.run_as Tutti i servizi Identità run-as per cui la richiesta viene autorizzata.
event:context.actor.context.is_on_behalf_of Tutti i servizi true quando un agente o un'app agisce per conto di un utente (on-behalf-of o OBO). Usarlo per scrivere criteri con riconoscimento dell'agente che si applicano solo quando un agente agisce per un utente.
event:context.actor.context.client_id Tutti i servizi ID client OAuth dell'identità che agisce, quando presente (chiamate OBO).
event:context.actor.context.actor_resource Tutti i servizi Risorsa dell'identità che agisce, ad esempio un agente, quando presente.
event:context.actor.context.is_actor_authenticated Tutti i servizi true quando l'identità agendo autenticata come client riservato.
event:context.tool.name, event:context.tool.arguments Servizi MCP Lo strumento chiamato e i relativi argomenti , ad esempio event:context.tool.arguments.repo.
event:context.message Servizi modello, Servizi provider di modelli Messaggio dell'ultimo utente o assistente estratto (indipendente dall'API). Usare questa opzione per i controlli del contenuto.
event:data Servizi modello, Servizi provider di modelli Payload completo della richiesta o della risposta.
event:request_data Servizi modello, Servizi provider di modelli La richiesta originale, disponibile durante la fase di output (ON RESULT).

Note

L'accesso al percorso (event:...) restituisce un oggetto VARIANT. Eseguirne il cast a un tipo scalare prima di confrontarlo con un valore letterale ,ad esempio event:type::string = 'request'; in caso contrario, il confronto non riesce con un DATATYPE_MISMATCH errore.

Etichette della richiesta

Le policy personalizzate possono valutare i tag inviati nell'intestazione Databricks-Ai-Gateway-Request-Tags :

Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}

Questo supporto si applica alle richieste Unity Gateway sui percorsi in cui vengono eseguite le policy di servizio, incluso MCP tools/call.

I tag provengono dalle intestazioni delle richieste e appaiono event:context insieme ad altri metadati delle policy. event:data e event:request_data contengono corpi di carico.

event:context.request_tags è un oggetto all'interno del eventVARIANT, con chiavi stringa e valori stringa, logicamente MAP<STRING, STRING>. Leggi un tag con event:context.request_tags.project::string. I tasti e i valori conservano maiuscolo, punteggiatura e stringhe vuote. Una richiesta senza l'intestazione ha un oggetto vuoto ({}). Entrambe le fasi di valutazione ricevono gli stessi tag di richiesta, inclusi trasformazioni di richiesta, tentativi e fallback del modello.

Di default, la dimensione combinata delle chiavi e dei valori decodificati è limitata a 10 KiB di dati UTF-8. Si applicano anche limiti di dimensione delle intestazione HTTP. Per esempi di SDK e REST, vedi Request tagging.

I servizi modello rifiutano le header tag malformate o sovradimensionate. Per le richieste MCP tools/call con policy di servizio applicabili, il gateway rifiuta anche queste intestazioni prima di valutare le policy, anche in modalità Log .

I tag sono forniti dal chiamante e sono separati dai tag di servizio e dal contesto dell'attore autenticato. Un tag da solo non stabilisce l'identità o il permesso di usare un progetto. Usa dati affidabili di identità e autorizzazione quando controlli quei permessi. Vedi Richiedere un progetto idoneo per un esempio di verifica del valore di un tag.

Si applicano le limitazioni seguenti:

  • I tag di richiesta non sono inclusi negli eventi inviati a fornitori di polizze esterni né vengono aggiunti automaticamente ai prompt LLM come giudice.
  • Le approvazioni MCP ASK non distinguono i tag delle richieste, e i prompt di approvazione non li mostrano. Un'approvazione può essere riutilizzata per una chiamata altrimenti corrispondente con tag diversi. Uso ALLOW e DENY decisioni per l'applicazione basata su tag. Queste decisioni vengono valutate su ogni richiesta.

Valore restituito

Un criterio personalizzato è un criterio decisionale: restituisce un oggetto con un VARIANT campo , resultALLOWo DENY (senza distinzione tra maiuscole e minuscole) e un oggetto facoltativoASK.reason Il result valore determina cosa accade:

  • ALLOW: l'interazione procede.
  • DENY: Azure Databricks blocca l'interazione. Invece di un errore, il chiamante riceve una risposta riuscita (HTTP 200) il cui turno assistente segnala il blocco, con il reason in un oggetto di livello superiore databricks_service_policy .
  • ASK: su un Servizio MCP, la richiesta si ferma per l'approvazione dell'utente prima che lo strumento venga eseguito. Se una policy SQL o Python personalizzata restituisce ASK un servizio modello o un servizio provider modello, Azure Databricks blocca la richiesta o la risposta perché questi servizi non possono chiedere l'approvazione all'utente.

Compilare il risultato con named_struct ed eseguire il wrapping in to_variant_object in modo che la funzione restituisca un VARIANToggetto , mantenendo result e reason come campi di primo livello. Un bare restituisce named_struct un STRUCToggetto e CAST(... AS VARIANT) non è supportato.

to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))

Il gateway accetta anche un modulo di busta di tipo forward-looking:

to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))

Note

Accesso al campo chiuso non riuscita: l'accesso a un campo che non esiste nel VARIANT parametro genera un errore e DENY genera un errore (l'accesso SQL VARIANT standard restituisce NULL per i campi mancanti). Ciò impedisce a un criterio di consentire un'interazione quando mancano i campi previsti.

SQL supportato

Azure Databricks traspila il corpo del criterio in CEL e lo valuta in fase di esecuzione, quindi il corpo della funzione supporta solo un subset limitato di SQL. Azure Databricks rifiuta una funzione o un costrutto non supportato quando si allegano i criteri e il criterio non riesce a chiudersi (DENY) durante la valutazione.

Category Supportato nel corpo dei criteri
Operatori Operatori di confronto, logici e aritmetici; \|\|, IN, LIKEe IS [NOT] NULL
Flusso di controllo CASE e IF
Cast CASTto INT/BIGINT, DOUBLE/FLOAT, STRINGo BOOLEAN; l'operatore ::
L'accesso ai dati Accesso al percorso VARIANT/JSON
Funzioni di stringa CONCAT LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIMRTRIM, , REPLACESTARTSWITH, , ENDSWITHCONTAINS
Altre funzioni COALESCE NULLIF, IFNULL, , NVL, ABSMOD, ISNULL, ISNOTNULL, , NAMED_STRUCTTO_VARIANT_OBJECT

Non supportato:ai_query, sottoquery, BETWEEN, funzioni di aggregazione, lambda/ EXISTSe variadic CONCAT o COALESCE.

  • Ultimo aggiornamento: