Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Importante
Este recurso está em versão Beta. Os administradores do espaço de trabalho podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações , optando pela pré-visualização das Políticas de Serviço Gateway Unity . Veja Gerir pré-visualizações no nível do espaço de trabalho.
Uma política de serviço SQL 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 uma política SQL.
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.request_tags |
Serviços de Modelo, Serviços de Prestadores de Modelo, Serviços MCP (tools/call) |
Um objeto JSON de chaves de strings fornecidas pelo chamador e valores de string. Ver etiquetas de Pedido. |
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.
Solicitar etiquetas
Políticas personalizadas podem avaliar as etiquetas enviadas no Databricks-Ai-Gateway-Request-Tags cabeçalho:
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
Este suporte aplica-se a pedidos Unity Gateway em caminhos onde as políticas de serviço são executadas, incluindo MCP tools/call.
As etiquetas vêm de cabeçalhos de pedidos e aparecem event:context juntamente com outros metadados de políticas.
event:data e event:request_data contêm corpos de carga útil.
event:context.request_tags é um objeto dentro do eventVARIANT, com chaves de cadeia e valores de cadeia, logicamente MAP<STRING, STRING>. Leia uma etiqueta com event:context.request_tags.project::string. As teclas e valores preservam maiúsculas, pontuação e cadeias vazias. Um pedido sem o cabeçalho tem um objeto vazio ({}). Ambas as fases de avaliação recebem as mesmas etiquetas de pedido, incluindo através de transformações de pedido, tentativas e reserva do modelo.
Por defeito, o tamanho combinado das chaves e valores decodificados está limitado a 10 KiB de dados UTF-8. Também se aplicam limites de tamanho do cabeçalho HTTP. Para exemplos de SDK e REST, veja Request tagging.
Os serviços de modelo rejeitam cabeçalhos de etiquetas mal formados ou sobredimensionados. Para pedidos MCP tools/call com políticas de serviço aplicáveis, o gateway também rejeita estes cabeçalhos antes de avaliar as políticas, incluindo no modo Log .
As etiquetas são fornecidas pelo chamador e são separadas das etiquetas de serviço e do contexto do ator autenticado. Uma etiqueta sozinha não estabelece identidade nem permissão para usar um projeto. Use dados de identidade e autorização confiáveis ao verificar essas permissões. Consulte Exigir um projeto elegível para um exemplo de verificação do valor de uma etiqueta.
Aplicam-se as seguintes limitações:
- As etiquetas de pedido não são incluídas em eventos enviados a fornecedores externos de apólices nem adicionadas automaticamente aos prompts do LLM como juiz.
- As aprovações MCP
ASKnão distinguem etiquetas de pedido, e os prompts de aprovação não as mostram. Uma aprovação pode ser reutilizada para uma chamada que seria compatível com etiquetas diferentes. UtilizaçãoALLOWeDENYdecisões para a aplicação baseada em etiquetas. Essas decisões são avaliadas em cada pedido.
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 oreasonnum objeto de topodatabricks_service_policy. -
ASK: num Serviço MCP, o pedido faz uma pausa para aprovação do utilizador antes de a ferramenta ser executada. Se uma política SQL ou Python personalizada for retornadaASKpara um Serviço de Modelo ou Serviço de Fornecedor de Modelos, o Azure Databricks bloqueia o pedido ou resposta porque estes serviços não podem pedir aprovação ao utilizador.
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
Um campo que não existe no VARIANT parâmetro lê-se como NULL, tal como no acesso SQL VARIANT padrão. Uma comparação que interpreta um corpo em falta, como =, , ou IN, gera um erro e resulta em DENY<. Isto impede que uma política permita uma interação quando os campos esperados estão em falta. Para tratar um campo que possa estar em falta, use uma função de manipulação nula como ISNULL ou COALESCE. Veja Funções de manuseamento nulo.
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, com o erro policy function '<name>' SQL cannot be transpiled to CEL, e a política falha ao fechar (DENY) na avaliação. Criar a função e executá-la na função Testar , verifica o corpo apenas como SQL. O Azure Databricks verifica a compatibilidade do CEL quando anexa a política, por isso anexa a política para confirmar que o corpo é suportado.
| 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.
Funções de manipulação nula
COALESCE, IFNULL, NVL, ISNULL, e ISNOTNULL falham a validação CEL quando o seu primeiro argumento é lançado para STRING dentro da chamada, por event:context.message::STRINGexemplo . Passa o campo de evento como VARIANT um valor em vez disso. Para COALESCE, IFNULL, e NVL, lança o resultado:
| Falha na validação do CEL | Passa a validação 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) |
O plano B pode ser literal, como '', ou outro campo de evento.
COALESCE aceita exatamente dois argumentos.
NULLIF também falha a validação CEL quando o seu primeiro argumento é lançado para STRING, por exemplo NULLIF(event:context.message::STRING, 'n/a').
Como um campo em falta lê-se como NULL, estas funções podem lidar com campos opcionais. Por exemplo, um pedido sem etiqueta project não event:context.request_tags.project tem campo, pelo que a seguinte condição é verdadeira:
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''