Referencia de la función de directiva de servicio

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 ASK no 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. Uso ALLOW y DENY decisiones 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 el reason en un objeto de nivel superior databricks_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 devuelve ASK una 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) = ''