Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Esta característica se encuentra en su versión beta. Los administradores de espacios de trabajo pueden controlar el acceso a esta función desde la página de Previsualizaciones optando por acceder a la vista previa de Políticas de Servicio Gateway de Unity . Consulte Gestionar vistas previas a nivel de espacio de trabajo.
Una política de servicio SQL personalizada es una función SQL definida por el usuario (UDF) registrada en el Catálogo de Unity que Azure Databricks evalúa en cada interacción con el servicio al que está vinculada. Esta página es el campo y la referencia de sintaxis para esas funciones. Para el procedimiento de extremo a extremo, véase Crear una política SQL.
Firma de función
Una función de directiva de servicio toma un único eventVARIANT parámetro y devuelve un VARIANT:
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
La función se ejecuta en ambos puntos de evaluación. Bifurque event:type::string en para decirles aparte:
-
'request': la fase de entrada (ON CALL), antes de que se invoque el servicio. -
'response': la fase de salida (ON RESULT), después de que el servicio responde.
Argumento event
event lleva los datos de interacción y el contexto. Los campos disponibles dependen del tipo de servicio:
| Campo | Se aplica a | Description |
|---|---|---|
event:type |
Todos los servicios | La fase: 'request' (entrada, EN LLAMADA) o 'response' (salida, EN RESULTADO). |
event:target |
Todos los servicios | El nombre completo del catálogo de Unity del servicio al que se adjunta la directiva (opcional). |
event:context.request_tags |
Servicios de Modelo, Servicios de Proveedor de Modelo, Servicios MCP (tools/call) |
Un objeto JSON de claves de cadena y valores de cadena suministrados por el llamador. Ver Etiquetas de solicitud. |
event:context.actor.run_as |
Todos los servicios | La identidad de ejecución en la que se autoriza la solicitud. |
event:context.actor.context.is_on_behalf_of |
Todos los servicios |
true cuando un agente o aplicación actúa en nombre de un usuario (en nombre de o de OBO). Úselo para escribir directivas compatibles con agente que solo se aplican cuando un agente actúa para un usuario. |
event:context.actor.context.client_id |
Todos los servicios | Identificador de cliente de OAuth de la identidad de actuación, cuando está presente (llama a OBO). |
event:context.actor.context.actor_resource |
Todos los servicios | Recurso de la identidad que actúa, como un agente, cuando está presente. |
event:context.actor.context.is_actor_authenticated |
Todos los servicios |
true cuando la identidad de actuación se autentica como un cliente confidencial. |
event:context.tool.name, event:context.tool.arguments |
Servicios MCP | La herramienta a la que se llama y sus argumentos (por ejemplo, event:context.tool.arguments.repo). |
event:context.message |
Servicios de modelo, servicios de proveedor de modelos | Mensaje del último usuario o asistente extraído (independiente de la API). Úselo para las comprobaciones de contenido. |
event:data |
Servicios de modelo, servicios de proveedor de modelos | Carga completa de solicitud o respuesta. |
event:request_data |
Servicios de modelo, servicios de proveedor de modelos | La solicitud original, disponible durante la fase de salida (EN RESULTADO). |
Nota:
Acceso de ruta de acceso (event:...) devuelve un VARIANT. Convertirlo a un tipo escalar antes de compararlo con un literal (por ejemplo, ); de lo contrario, event:type::string = 'request'se produce un DATATYPE_MISMATCH error en la comparación.
Etiquetas de la solicitud
Las políticas personalizadas pueden evaluar las etiquetas enviadas en el Databricks-Ai-Gateway-Request-Tags encabezado:
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
Este soporte se aplica a las solicitudes de Unity Gateway en rutas donde se ejecutan las políticas de servicio, incluyendo MCP tools/call.
Las etiquetas provienen de encabezados de peticiones y aparecen junto event:context a otros metadatos de políticas.
event:data y event:request_data contienen cuerpos de carga útil.
event:context.request_tags es un objeto dentro de , eventVARIANTcon claves de cadena y valores de cadena, lógicamente MAP<STRING, STRING>. Lee una etiqueta con event:context.request_tags.project::string. Las teclas y valores conservan mayúsculas, puntuación y cadenas vacías. Una petición sin encabezado tiene un objeto vacío ({}). Ambas fases de evaluación reciben las mismas etiquetas de solicitud, incluyendo transformaciones de solicitud, intentos y respaldo del modelo.
Por defecto, el tamaño combinado de las claves y valores decodificados está limitado a 10 KiB de datos UTF-8. También se aplican límites de tamaño de cabecera HTTP. Para ejemplos de SDK y REST, véase Etiquetado de solicitudes.
Los servicios de modelo rechazan encabezados de etiquetas mal formados o sobredimensionados. Para solicitudes MCP tools/call con políticas de servicio aplicables, la pasarela también rechaza estos encabezados antes de evaluar las políticas, incluso en modo Registro .
Las etiquetas son proporcionadas por el llamante y son independientes de las etiquetas de servicio y del contexto del actor autenticado. Una etiqueta por sí sola no establece identidad ni permiso para usar un proyecto. Utiliza datos de identidad y autorización confiables al comprobar esos permisos. Consulte Exigir un proyecto elegible para un ejemplo de verificación del valor de una etiqueta.
Se presentan las siguientes limitaciones:
- Las etiquetas de solicitud no se incluyen en eventos enviados a proveedores externos de pólizas ni se añaden automáticamente a los indicios de LLM como juez.
- Las aprobaciones MCP
ASKno distinguen etiquetas de solicitud, y los indicaciones de aprobación no las muestran. Una aprobación puede reutilizarse para una llamada que de otro modo coincidiría con etiquetas diferentes. UsoALLOWyDENYdecisiones para la aplicación basada en etiquetas. Esas decisiones se evalúan en cada solicitud.
Valor devuelto
Una directiva personalizada es una directiva de decisión: devuelve un VARIANT con un result campo de ALLOW, DENYo ASK (sin distinción entre mayúsculas y minúsculas) y un opcional reason. El result valor determina lo que sucede:
-
ALLOW: la interacción continúa. -
DENY: Azure Databricks bloquea la interacción. En lugar de un error, el llamador recibe una respuesta exitosa (HTTP 200) cuyo turno asistente reporta el bloqueo, con elreasonen un objeto de nivel superiordatabricks_service_policy. -
ASK: en un Servicio MCP, la solicitud se pausa para la aprobación del usuario antes de que la herramienta se ejecute. Si se devuelveASKuna política personalizada de SQL o Python para un Servicio de Modelo o Servicio de Proveedor de Modelos, Azure Databricks bloquea la solicitud o respuesta porque estos servicios no pueden solicitar la aprobación del usuario.
Compile el resultado con named_struct y encapsularlo para to_variant_object que la función devuelva un , VARIANTmanteniendo result y reason como campos de nivel superior. Un elemento bare named_struct devuelve un STRUCTy CAST(... AS VARIANT) no se admite.
to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))
La puerta de enlace también acepta un formulario de sobre de avance:
to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))
Nota:
Un campo que no existe en el VARIANT parámetro se lee como NULL, como en el acceso SQL VARIANT estándar. Una comparación que lee un campo faltante, como =, , o IN, genera un error y da lugar a DENY<. Esto impide que una directiva permita una interacción cuando falten campos esperados. Para manejar un campo que podría faltar, se utiliza una función de manejo nulo como ISNULL o COALESCE. Ver Funciones de manejo nulo.
SQL compatible
Azure Databricks transpila el cuerpo de la directiva a CEL y lo evalúa en tiempo de ejecución, por lo que el cuerpo de la función solo admite un subconjunto restringido de SQL. Azure Databricks rechaza una función o constructo no soportado cuando adjuntas la política, con el error policy function '<name>' SQL cannot be transpiled to CEL, y la política falla al cerrarse (DENY) en la evaluación. Crear la función y ejecutarla en la función Test , comprueba el cuerpo solo como SQL. Azure Databricks comprueba la compatibilidad con CEL cuando adjuntas la política, así que adjunta la política para confirmar que el cuerpo está soportado.
| Categoría | Se admite en el cuerpo de la directiva |
|---|---|
| Operadores | Operadores de comparación, lógicos y aritméticos; \|\|, IN, LIKEy IS [NOT] NULL |
| Flujo de control |
CASE y IF |
| Casteos |
CASTa INT/BIGINT, DOUBLE/FLOAT, STRINGo BOOLEAN; el operador :: |
| Acceso a datos | Acceso a la ruta de acceso VARIANT/JSON |
| Funciones de cadena |
CONCAT, LENGTH, CHAR_LENGTH, UPPER, , LOWERSUBSTRING, TRIM, LTRIMRTRIMREPLACESTARTSWITHENDSWITHCONTAINS |
| Otras funciones |
COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, , NAMED_STRUCTTO_VARIANT_OBJECT |
No compatible:ai_query, subconsultas, BETWEEN, funciones de agregado, lambdas/ EXISTS, y variadic CONCAT o COALESCE.
Funciones de manejo nulo
COALESCE, IFNULL, NVL, ISNULL, y ISNOTNULL fallan la validación CEL cuando su primer argumento se lanza dentro STRING de la llamada, por event:context.message::STRINGejemplo . Pasa el campo de evento como VARIANT un valor en su lugar. Para COALESCE, IFNULL, y NVL, se obtiene el resultado:
| Falla la validación CEL | Supera la validación CEL |
|---|---|
COALESCE(event:context.message::STRING, '') |
CAST(COALESCE(event:context.message, '') AS STRING) |
IFNULL(event:context.message::STRING, '') |
CAST(IFNULL(event:context.message, '') AS STRING) |
NVL(event:context.message::STRING, '') |
CAST(NVL(event:context.message, '') AS STRING) |
ISNULL(event:context.message::STRING) |
ISNULL(event:context.message) |
ISNOTNULL(event:context.message::STRING) |
ISNOTNULL(event:context.message) |
El respaldo puede ser un campo literal, como '', u otro campo de evento.
COALESCE acepta exactamente dos argumentos.
NULLIF también falla la validación CEL cuando su primer argumento se convierte en STRING, por ejemplo NULLIF(event:context.message::STRING, 'n/a').
Como un campo que falta se lee como NULL, estas funciones pueden manejar campos opcionales. Por ejemplo, una petición sin project etiqueta no tiene campo event:context.request_tags.project , por lo que se cumple la siguiente condición:
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''