Référence de la fonction de politique de service
Bêta
Cette fonctionnalité est en Bêta. Les administrateurs de Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Aperçus en choisissant de participer à l'aperçu des stratégies de service passerelle Unity . Consultez Gérer les aperçus au niveau du workspace.
Une fonction de règle de service personnalisée est une fonction définie par l'utilisateur (UDF) inscrite dans Unity Catalog que Databricks évalue à chaque interaction avec le service auquel elle est associée. Cette page est la référence des champs et de la syntaxe de ces fonctions. Pour la procédure complète, consultez Créer une règle SQL.
Signature de fonction
Une fonction de politique de service SQL prend un seul parameter event VARIANT et renvoie un VARIANT.
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
Pour les APIs de modèle de style chat et les appels d’outil MCP, 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 l'appel du service.'response': la phase de sortie (ON RESULT), une fois que le service répond.
Pour les demandes d’intégration, la fonction reçoit uniquement l’événement 'request' et lit l’entrée à partir de event:data.input. Elle n’inspecte pas les vecteurs d’intégration. Les APIs de réponses utilisent également event:data.input, donc sa présence seule n’identifie pas les demandes d’intégration. Utilisez un service distinct lorsqu’une politique doit s’appliquer uniquement aux intégrations.
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 de l’utilisateur ou de l’assistant extrait (indépendant de l’API) pour les APIs de modèle de type chat. Ce champ est absent pour les embeddings. Lisez plutôt |
| Services de modèle, Services de fournisseur de modèle | Un tableau d'objets de message neutres par rapport au fournisseur dans la fenêtre de conversation configurée pour les APIs de modèle de style chat. Absent pour les embeddings. Disponible pour les fonctions SQL et Python personnalisées pendant l'évaluation des entrées et des sorties, y compris lorsque la fenêtre est définie sur un tour. Lors de l'évaluation de la sortie, le tableau contient la fenêtre de conversation de la demande d'origine. |
| Services de modèle, Services de fournisseur de modèle | Absent pour les embeddings. Pour les APIs de modèle de style chat, le texte du message le plus récent de l'utilisateur dans la conversation complète, même lorsque la fenêtre configurée exclut ce message. |
| 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.
Contexte de la conversation
Pour une fonction SQL ou Python personnalisée évaluant une API de modèle de type chat, vous pouvez configurer une fenêtre de conversation. Pour toute valeur configurée, y compris un tour, event:context.conversation possède cette forme neutre vis-à-vis du fournisseur lors de l’évaluation des entrées et des sorties. Lors de l’évaluation des sorties, l’objet contient la conversation de la requête d’origine.
{
"conversation": [
{ "role": "user", "content": "First question" },
{ "role": "assistant", "content": "First answer" },
{ "role": "user", "content": "Follow-up question" }
],
"latest_input": "Follow-up question"
}
Le tableau conversation contient la fenêtre configurée. latest_input contient le message utilisateur le plus récent de la conversation complète, même lorsque ce message se trouve en dehors de la fenêtre. Si le contexte de conversation en plusieurs tours est désactivé pour le workspace, chaque fenêtre configurée est traitée comme un seul tour.
La passerelle conserve event:context.message et event:data, de sorte que les fonctions existantes continuent à recevoir le message unique extrait et la charge utile complète du fournisseur. L'objet de conversation n'est pas ajouté lorsque la fenêtre est non définie, pour les embeddings ou pour les services MCP.
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 automatiquement ajoutées aux invites LLM-as-a-judge. Les politiques de service externe les reçoivent, comme décrit dans la référence de l’API de politique de service externe.
- 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 règle SQL personnalisée est une règle de décision : elle retourne un VARIANT avec un champ result de ALLOW, DENY ou ASK (sensibilité à la casse non prise en compte) et un reason optionnel. La valeur result détermine ce qui se passe :
ALLOW: l’interaction se déroule.DENY: Databricks bloque l'interaction. Pour les APIs de modèle de style chat, l'appelant reçoit une réponse réussie (HTTP 200) au lieu d'une erreur. Pour ces APIs sur un service de modèle ou un service de fournisseur de modèle, le tour de l'assistant signale le blocage, avec lereasondans un objetdatabricks_service_policyde niveau supérieur. Un refus d'embedding renvoie HTTP 400 pour toute la requête avant que le modèle ne s'exécute. Sur un service MCP, la réponse est une erreur JSON-RPC avec lereasondanserror.message.ASK: sur un service MCP, la demande est mise en pause pour approbation par l’utilisateur avant l’exécution de l’outil. Si une fonction de politique personnalisée renvoieASKpour un service de modèle ou un service de fournisseur de modèle, Databricks bloque la demande 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', '...')))
Un champ qui n'existe pas dans le parameter VARIANT est lu comme NULL, comme dans l'accès VARIANT SQL standard. Une comparaison qui lit un champ manquant, tel que =, < ou IN, déclenche une erreur et aboutit à DENY. Cela empêche une stratégie d'autoriser une interaction lorsque les champs attendus sont manquants. Pour gérer un champ qui pourrait être manquant, utilisez une fonction de gestion des valeurs nulles telle que ISNULL ou COALESCE. Voir Fonctions de gestion des valeurs nulles.
SQL pris en charge
Databricks transpile le corps de la politique en CEL et l'évalue lors de l'exécution ; le corps de la fonction ne prend donc 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, avec l'erreur policy function '<name>' SQL cannot be transpiled to CEL, et la politique échoue en étant fermée (DENY) lors de l'évaluation. La création de la fonction et son exécution dans Tester la fonction vérifient uniquement le corps en tant que SQL. Databricks vérifie la compatibilité CEL lorsque vous attachez la politique ; attachez-la donc pour confirmer que le corps est pris en charge.
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.
Fonctions de gestion des valeurs NULL
COALESCE, IFNULL, NVL, ISNULL et ISNOTNULL échouent à la validation CEL lorsque leur premier argument est converti en STRING dans l'appel, par exemple event:context.message::STRING. Transmettez le champ d'événement en tant que valeur VARIANT à la place. Pour COALESCE, IFNULL et NVL, convertissez le résultat :
Échec de la validation CEL | Validation CEL réussie |
|---|---|
|
|
|
|
|
|
|
|
|
|
Le fallback peut être un littéral, tel que '', ou un autre champ d'événement. COALESCE accepte exactement deux arguments.
NULLIF échoue également à la validation CEL lorsque son premier argument est casté en STRING, par exemple NULLIF(event:context.message::STRING, 'n/a').
Comme un champ manquant est lu comme NULL, ces fonctions peuvent traiter des champs optionnels. Par exemple, une requête sans balise project n'a pas de champ event:context.request_tags.project, donc la condition suivante est vraie :
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''