Referencia de la función de directiva de servicio

Importante

Esta característica se encuentra en su versión beta. Los administradores de cuentas pueden controlar el acceso a esta característica desde la página Vista previa de la consola de la cuenta. Consulte Administrar versiones preliminares de Azure Databricks.

Una directiva de servicio personalizada es una función definida por el usuario (UDF) de SQL registrada en el Catálogo de Unity que Azure Databricks evalúa en cada interacción con el servicio al que está asociado. Esta página es el campo y la referencia de sintaxis para esas funciones. Para obtener el procedimiento de un extremo a otro, consulte Creación y asociación de una directiva de servicio.

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.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.

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: la interacción se detiene para la aprobación humana antes de continuar.

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:

Acceso a campos cerrados por error: el acceso a un campo que no existe en el VARIANT parámetro genera un error y da como DENY resultado (el acceso SQL VARIANT estándar devuelve NULL los campos que faltan). Esto impide que una directiva permita una interacción cuando falten campos esperados.

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 construcción no admitidas al adjuntar la directiva y la directiva no se cierra (DENY) en la evaluación.

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.

  • Last updated on