Référence de la fonction de politique de service
Bêta
Cette fonctionnalité est en Bêta. Les administrateurs de compte peuvent contrôler l'accès à cette fonctionnalité depuis la page Aperçus de la console de compte. Consultez Gérer les aperçus Databricks.
Une politique de service SQL personnalisée est une fonction définie par l'utilisateur (UDF) SQL enregistrée dans Unity Catalog que Databricks évalue à chaque interaction avec le service auquel elle est rattachée. Cette page présente les références relatives aux champs et à la syntaxe de ces fonctions. Pour connaître la procédure de bout en bout, consultez Créer une politique SQL.
Signature de fonction
Une fonction de politique de service prend un seul paramètre event VARIANT et retourne un VARIANT:
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
La fonction s'exécute aux deux points d'évaluation. Branch sur event:type::string pour les distinguer :
'request': la phase d' entrée ( ON CALL ), avant que le service ne soit appelé.'response': la phase de sortie ( ON RESULT ), après que le service a répondu.
L’argument event
event contient les données d'interaction et le contexte. Les champs disponibles dépendent du type de service :
Champ | S'applique à | Description |
|---|---|---|
| Tous les services | La phase : |
| Tous les services | Le nom complet Unity Catalog du service auquel la stratégie est associée (facultatif). |
| Services de modèle, services de fournisseur de modèle, services MCP ( | Un objet JSON de clés de chaînes et de valeurs de chaînes fournies par l'appelant. Voir Tags de requête. |
| Tous les services | L'identité d'exécution à laquelle la requête s'authentifie. |
| Tous les services |
|
| Tous les services | L'ID client OAuth de l'identité agissante, le cas échéant (appels OBO). |
| Tous les services | La ressource de l'identité agissante, telle qu'un agent, le cas échéant. |
| Tous les services |
|
| Services MCP | L'outil appelé et ses arguments (par exemple, |
| Services de modèle, Services de fournisseur de modèle | Le dernier message d’utilisateur ou d’assistant extrait (agnostique de l’API). Utilisez ceci pour les vérifications de contenu. |
| Services de modèle, Services de fournisseur de modèle | La charge utile de la requête ou de la réponse complète. |
| Services de modèle, Services de fournisseur de modèle | La requête originale, disponible lors de la phase de sortie (ON RESULT). |
L'accès au chemin (event:...) renvoie un VARIANT. Convertissez-le en un type scalaire avant de le comparer à un littéral (par exemple, event:type::string = 'request') ; sinon, la comparaison échoue avec une erreur DATATYPE_MISMATCH.
Demander des tags
Les politiques personnalisées peuvent évaluer les tags envoyés dans l’en-tête Databricks-Ai-Gateway-Request-Tags :
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
Cette prise en charge s’applique aux requêtes Unity Gateway sur les chemins où s’exécutent les stratégies de service, y compris MCP tools/call.
Les tags proviennent des en-têtes de requête et apparaissent dans event:context aux côtés d'autres métadonnées de politique. event:data et event:request_data contiennent des corps de payload.
event:context.request_tags est un objet situé à l’intérieur de event VARIANT, avec des clés de chaînes et des valeurs de chaînes, logiquement MAP<STRING, STRING>. Lire un tag avec event:context.request_tags.project::string. Les clés et les valeurs conservent la casse, la ponctuation et les chaînes vides. Une requête sans l’en-tête comporte un objet vide ({}). Les deux phases d’évaluation reçoivent les mêmes tags de requête, y compris par le biais de transformations de requêtes, de nouvelles tentatives et du fallback de modèle.
Par default, la taille combinée des clés et des valeurs décodées est limitée à 10 Kio de données UTF-8. Des limites de taille d’en-tête HTTP s’appliquent également. Pour des exemples relatifs au SDK et à REST, consultez Request tagging.
Model services reject malformed or oversized tag headers. For MCP tools/call requests with applicable service policies, the gateway also rejects these headers before evaluating the policies, including in Log mode.
Les tags sont fournis par l’appelant et sont distincts des tags de service et du contexte d’acteur authentifié. Un tag seul n’établit pas d’identité ni d’autorisation d’utiliser un projet. Utilisez des données d’identité et d’autorisation fiables lors de la vérification de ces autorisations. Consultez Demander un projet éligible pour voir un exemple de vérification de la valeur d’un tag.
Les limitations suivantes s’appliquent :
- Les balises de requête ne sont pas incluses dans les événements envoyés aux fournisseurs de politiques externes ni ajoutées automatiquement aux invites LLM-as-a-judge.
- Les approbations MCP
ASKne distinguent pas les tags de demande, et les invites d’approbation ne les affichent pas. Une approbation peut être réutilisée pour un appel par ailleurs correspondant doté de tags différents. Utilisez les décisionsALLOWetDENYpour l’application basée sur les tags. Ces décisions sont évaluées à chaque requête.
Valeur de retour
Une politique personnalisée est une politique de décision : elle renvoie un VARIANT avec un champ result de ALLOW, DENY ou ASK (non sensible à la casse) et un reason facultatif. La valeur result détermine ce qui se passe :
ALLOW: l’interaction se déroule.DENY: Databricks bloque l’interaction. Au lieu d’une erreur, l’appelant reçoit une réponse réussie (HTTP 200) dont le tour d’assistant signale le bloc, avec lereasondans un objetdatabricks_service_policyde haut niveau.ASK: sur un service MCP, la requête se met en pause pour obtenir l’approbation de l’utilisateur avant l’exécution de l’outil. Si une stratégie SQL ou Python personnalisée renvoieASKpour un service de modèle ou un service de fournisseur de modèle, Databricks bloque la requête ou la réponse, car ces services ne peuvent pas demander l’approbation de l’utilisateur.
Construisez le résultat avec named_struct et enveloppez-le dans to_variant_object afin que la fonction renvoie un VARIANT, en gardant result et reason comme champs de niveau supérieur. Un simple named_struct renvoie un STRUCT, et CAST(... AS VARIANT) n'est pas pris en charge.
to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))
La passerelle accepte également un formulaire d'enveloppe prospective :
to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))
Accès au champ en mode de défaillance fermée : L'accès à un champ qui n'existe pas dans le paramètre VARIANT déclenche une erreur et entraîne DENY (l'accès SQL VARIANT standard retourne NULL pour les champs manquants). Cela empêche une politique d'autoriser une interaction lorsque des champs attendus sont manquants.
SQL pris en charge
Databricks transpile le corps de la politique en CEL et l'évalue lors de l'exécution, de sorte que le corps de la fonction ne prend en charge qu'un sous-ensemble restreint de SQL. Databricks rejette une fonction ou une construction non prise en charge lorsque vous attachez la politique, et la politique échoue en mode fermé (DENY) lors de l'évaluation.
Catégorie | Pris en charge dans le corps de la politique |
|---|---|
Opérateurs | Opérateurs de comparaison, logiques et arithmétiques ; |
Flux de contrôle |
|
Conversions |
|
Accès aux données | Accès au chemin VARIANT/JSON |
Fonctions de chaîne |
|
Autres fonctions |
|
Non pris en charge : ai_query, les sous-requêtes, BETWEEN, les fonctions d'agrégation, les lambdas/ EXISTS, et les CONCAT ou COALESCE variadiques.