Referência da função da política de serviço

info

Beta

Este recurso está em Beta. Os administradores de account podem controlar o acesso a este recurso a partir da página **Previews** do console da account. Consulte Gerenciar prévias do Databricks.

Uma política de serviço personalizada é uma função definida pelo usuário (UDF) de SQL registrada no Unity Catalog que o Databricks avalia em cada interação com o serviço ao qual está anexada. Esta página é a referência de campo e sintaxe para essas funções. Para o procedimento completo, consulte Criar e anexar uma política de serviço.

Assinatura de função

Uma função de política de serviço aceita um único parâmetro event VARIANT e retorna um VARIANT:

SQL

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

A função realiza a execução em ambos os pontos de avaliação. Ramifique em event:type::string para distingui-los:

• 'request': a fase ON CALL , antes que o serviço seja invocado.
• 'response': a fase ON RESULT , depois que o serviço responde.

O argumento event

event contém os dados e o contexto da interação. Os campos disponíveis dependem do tipo de serviço:

campo	Aplica-se a	Descrição
event:type	Todos os serviços	A fase: 'request' (EM CHAMADA) ou 'response' (NO RESULTADO).
event:target	Todos os serviços	O nome completo do Unity Catalog do serviço ao qual a política está anexada (opcional).
event:context.actor.run_as	Todos os serviços	A identidade de execução com a qual a solicitação é autorizada.
event:context.actor.context.is_on_behalf_of	Todos os serviços	true quando um agente ou aplicativo está agindo em nome de um usuário (em nome de, ou OBO). Use-o para escrever políticas cientes de agentes que se aplicam somente quando um agente age em nome de um usuário.
event:context.actor.context.client_id	Todos os serviços	O ID do cliente OAuth da identidade que está atuando, quando presente (chamadas OBO).
event:context.actor.context.actor_resource	Todos os serviços	O recurso da identidade em ação, como um agente, quando presente.
event:context.actor.context.is_actor_authenticated	Todos os serviços	true quando a identidade atuante autenticada como um cliente confidencial.
event:context.tool.name, event:context.tool.arguments	Serviços MCP	A ferramenta que está sendo chamada e seus argumentos (por exemplo, event:context.tool.arguments.repo).
event:context.message	Serviços de Modelo	A última mensagem de usuário ou assistente extraída (independente de API). Use isto para verificações de conteúdo.
event:data	Serviços de Modelo	O payload completo de solicitação ou resposta.
event:request_data	Serviços de Modelo	A solicitação original, disponível durante ON RESULT.

nota

O acesso ao caminho (event:...) retorna um VARIANT. Converta-o para um tipo escalar antes de compará-lo a um literal (por exemplo, event:type::string = 'request'); caso contrário, a comparação falha com um erro DATATYPE_MISMATCH.

Valor de retorno

Uma política personalizada é uma Política de Decisão: ela retorna um VARIANT com um campo result de ALLOW, DENY ou ASK (não diferencia maiúsculas de minúsculas) e um reason opcional. O valor result determina o que acontece:

• ALLOW: a interação prossegue.
• DENY: Databricks bloqueia a interação. O chamador recebe um erro estruturado com o reason.
• ASK: a interação pausa para aprovação humana antes de prosseguir.

Crie o resultado com named_struct e envolva-o em to_variant_object para que a função retorne um VARIANT, mantendo result e reason como campos de nível superior. Um named_struct simples retorna um STRUCT, e CAST(... AS VARIANT) não é compatível.

SQL

to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))

O gateway também aceita um formulário de envelope prospectivo:

SQL

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

nota

Acesso a campo com falha fechada : Acessar um campo que não existe no parâmetro VARIANT gera um erro e resulta em DENY (o acesso SQL VARIANT padrão retorna NULL para campos ausentes). Isso impede que uma política permita uma interação quando os campos esperados estiverem ausentes.

SQL compatível

A Databricks transpila o corpo da política para CEL e o avalia em tempo de execução, portanto, o corpo da função oferece suporte apenas a um subconjunto restrito de SQL. A Databricks rejeita uma função ou construção não compatível ao anexar a política, e a política falha fechada (DENY) na avaliação.

Categoria	Compatível no corpo da política
Operadores	Operadores de comparação, lógicos e aritméticos; ||, IN, LIKE e IS [NOT] NULL
Fluxo de controle	CASE e IF
Conversões	CAST para INT/BIGINT, DOUBLE/FLOAT, STRING, ou BOOLEAN; o operador ::
Acesso aos dados	VARIANTE / acesso ao caminho JSON
Funções de strings	CONCAT, LENGTH, CHAR_LENGTH, UPPER, LOWER, SUBSTRING, TRIM, LTRIM, RTRIM, REPLACE, STARTSWITH, ENDSWITH, CONTAINS
Outras funções	COALESCE, NULLIF, IFNULL, NVL, ABS, MOD, ISNULL, ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT

Não suportado: ai_query, subqueries, BETWEEN, funções de agregação, lambdas / EXISTS e CONCAT ou COALESCE variádicos.

Relacionado

• Políticas de serviço para recursos protegíveis de IA
• Crie e anexe uma política de serviço