Référence de la fonction de politique de service

info

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 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 attachée. Cette page est la référence de champ et de syntaxe pour ces fonctions. Pour la procédure de bout en bout, consultez Créer et attacher une politique de service.

Signature de fonction

Une fonction de politique de service prend un seul paramètre event VARIANT et retourne un VARIANT:

SQL

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 **ON CALL**, avant que le service ne soit invoqué.
• 'response': la phase ON RESULT , après que le service ait 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
event:type	Tous les services	La phase : 'request' (ON CALL) ou 'response' (ON RESULT).
event:target	Tous les services	Le nom complet Unity Catalog du service auquel la stratégie est associée (facultatif).
event:context.actor.run_as	Tous les services	L'identité d'exécution à laquelle la requête s'authentifie.
event:context.actor.context.is_on_behalf_of	Tous les services	true lorsqu'un agent ou une application agit au nom d'un utilisateur (au nom de, ou OBO). Utilisez-le pour écrire des politiques sensibles aux agents qui s'appliquent uniquement lorsqu'un agent agit pour un utilisateur.
event:context.actor.context.client_id	Tous les services	L'ID client OAuth de l'identité agissante, le cas échéant (appels OBO).
event:context.actor.context.actor_resource	Tous les services	La ressource de l'identité agissante, telle qu'un agent, le cas échéant.
event:context.actor.context.is_actor_authenticated	Tous les services	true lorsque l'identité agissante s'est authentifiée en tant que client confidentiel.
event:context.tool.name, event:context.tool.arguments	Services MCP	L'outil appelé et ses arguments (par exemple, event:context.tool.arguments.repo).
event:context.message	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.
event:data	Services de modèle, Services de fournisseur de modèle	La charge utile de la requête ou de la réponse complète.
event:request_data	Services de modèle, Services de fournisseur de modèle	La requête originale, disponible pendant ON RESULT.

Champ	S'applique à	Description
event:type	Tous les services	La phase : 'request' (ON CALL) ou 'response' (ON RESULT).
event:target	Tous les services	Le nom complet Unity Catalog du service auquel la stratégie est associée (facultatif).
event:context.actor.run_as	Tous les services	L'identité d'exécution à laquelle la requête s'authentifie.
event:context.actor.context.is_on_behalf_of	Tous les services	true lorsqu'un agent ou une application agit au nom d'un utilisateur (au nom de, ou OBO). Utilisez-le pour écrire des politiques sensibles aux agents qui s'appliquent uniquement lorsqu'un agent agit pour un utilisateur.
event:context.actor.context.client_id	Tous les services	L'ID client OAuth de l'identité agissante, le cas échéant (appels OBO).
event:context.actor.context.actor_resource	Tous les services	La ressource de l'identité agissante, telle qu'un agent, le cas échéant.
event:context.actor.context.is_actor_authenticated	Tous les services	true lorsque l'identité agissante s'est authentifiée en tant que client confidentiel.
event:context.tool.name, event:context.tool.arguments	Services MCP	L'outil appelé et ses arguments (par exemple, event:context.tool.arguments.repo).
event:context.message	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.
event:data	Services de modèle, Services de fournisseur de modèle	La charge utile de la requête ou de la réponse complète.
event:request_data	Services de modèle, Services de fournisseur de modèle	La requête originale, disponible pendant ON RESULT.

remarque

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.

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. L'appelant reçoit une erreur structurée avec le reason.
• ASK: l'interaction est interrompue pour une approbation humaine avant de continuer.

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.

SQL

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 :

SQL

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

remarque

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 ; ||, IN, LIKE et IS [NOT] NULL
Flux de contrôle	CASE et IF
Conversions	CAST à INT/BIGINT, DOUBLE/FLOAT, STRING, ou BOOLEAN; l'opérateur ::
Accès aux données	Accès au chemin VARIANT/JSON
Fonctions de chaîne	CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, RTRIM, REPLACE, STARTSWITH, ENDSWITH, CONTAINS
Autres fonctions	COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT

Catégorie	Pris en charge dans le corps de la politique
Opérateurs	Opérateurs de comparaison, logiques et arithmétiques ; ||, IN, LIKE et IS [NOT] NULL
Flux de contrôle	CASE et IF
Conversions	CAST à INT/BIGINT, DOUBLE/FLOAT, STRING, ou BOOLEAN; l'opérateur ::
Accès aux données	Accès au chemin VARIANT/JSON
Fonctions de chaîne	CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, RTRIM, REPLACE, STARTSWITH, ENDSWITH, CONTAINS
Autres fonctions	COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT

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.

Associés

• Stratégies de service pour les éléments sécurisables d'IA
• Créer et associer une politique de service