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

Importante

Este recurso está em versão Beta. Os administradores de conta podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações da consola da conta. Ver Gerir as pré-visualizações de Azure Databricks.

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

Assinatura da função

Uma função de política de serviço toma um único eventVARIANT parâmetro e devolve um VARIANT:

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

A função executa-se em ambos os pontos de avaliação. Avance event:type::string para os distinguir:

  • 'request': a fase de entrada (ON CALL), antes de o serviço ser invocado.
  • 'response': a fase de saída (ON RESULT), após a resposta do serviço.

O event argumento

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

Field Aplica-se a Description
event:type Todos os serviços A fase: 'request' (entrada, EM CHAMADA) ou 'response' (saída, NO RESULTADO).
event:target Todos os serviços O nome completo do Unity Catalog do serviço a que a política está associada (opcional).
event:context.actor.run_as Todos os serviços A identidade run-as contra a qual o pedido autoriza.
event:context.actor.context.is_on_behalf_of Todos os serviços true quando um agente ou aplicação atua em nome de um utilizador (em nome de, ou OBO). Use-o para escrever políticas conscientes do agente que se aplicam apenas quando um agente atua em nome de um utilizador.
event:context.actor.context.client_id Todos os serviços O ID do cliente OAuth da identidade atuante, quando presente (chamadas OBO).
event:context.actor.context.actor_resource Todos os serviços O recurso da identidade atuante, como um agente, quando presente.
event:context.actor.context.is_actor_authenticated Todos os serviços true quando a identidade interina foi autenticada como cliente confidencial.
event:context.tool.name, event:context.tool.arguments Serviços MCP A ferramenta que está a ser chamada e os seus argumentos (por exemplo, event:context.tool.arguments.repo).
event:context.message Serviços de Modelo, Serviços de Prestadores de Modelos A última mensagem do utilizador ou assistente extraída (independente da API). Usa isto para verificações de conteúdo.
event:data Serviços de Modelo, Serviços de Prestadores de Modelos A carga útil completa de pedidos ou respostas.
event:request_data Serviços de Modelo, Serviços de Prestadores de Modelos O pedido original, disponível durante a fase de saída (NO RESULTADO).

Note

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

Valor de retorno

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

  • ALLOW: a interação prossegue.
  • DENY: Azure Databricks bloqueia a interação. Em vez de um erro, o chamador recebe uma resposta bem-sucedida (HTTP 200) cujo turno assistente reporta o bloqueio, com o reason num objeto de topo databricks_service_policy .
  • ASK: a interação faz uma pausa para aprovação humana antes de prosseguir.

Construa o resultado com named_struct e envolva-o to_variant_object para que a função devolva um VARIANT, mantendo result e reason como campos de topo de nível. Um nudo named_struct devolve um STRUCT, e CAST(... AS VARIANT) não é suportado.

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

O portal também aceita um formulário de envelope orientado para o futuro:

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

Note

Acesso de campo falhado e fechado: Aceder a um campo que não existe no VARIANT parâmetro gera um erro e resulta em DENY (retornos VARIANT padrão de acesso SQL NULL para campos em falta). Isto impede que uma política permita uma interação quando os campos esperados estão em falta.

SQL suportado

O Azure Databricks transpila o corpo da política para o CEL e avalia-o em tempo de execução, pelo que o corpo da função suporta apenas um subconjunto restrito de SQL. O Azure Databricks rejeita uma função ou construto não suportado quando anexa a política, e a política falha ao fechar (DENY) na avaliação.

Categoria Apoiado no órgão político
Operadores Operadores de comparação, lógicos e aritméticos; \|\|, IN, LIKE, e IS [NOT] NULL
Fluxo de controle CASE e IF
Conversões de Tipos CAST para INT/BIGINT, DOUBLE/FLOAT, STRING, ou BOOLEAN; o :: operador
Acesso a dados VARIANT / Acesso ao caminho JSON
Funções de cadeia de caracteres CONCAT, LENGTH, CHAR_LENGTH, , UPPER, LOWER, , SUBSTRINGTRIMLTRIMRTRIMREPLACESTARTSWITHENDSWITHCONTAINS
Outras funções COALESCE, NULLIF, IFNULLNVL, , ABS, , MODISNULLISNOTNULLNAMED_STRUCTTO_VARIANT_OBJECT

Não suportado:ai_query, subqueries, BETWEEN, funções agregadas, lambdas / EXISTS, e variadic CONCAT ou COALESCE.

  • Last updated on