Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Importante
Esse recurso está em Beta. Administradores de workspace podem controlar o acesso a esse recurso a partir da página de Pré-visualizações optando pela prévia das Políticas de Serviço do Gateway Unity . Consulte Gerenciar visualizações no nível do espaço de trabalho.
Uma função de política de serviço personalizada é uma função definida pelo usuário (UDF) registrada no Unity Catalog que o Azure Databricks avalia a cada interação com o serviço ao qual está vinculada. 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.
Para funções de política em Python, veja funções de política em Python e Escreva uma política de serviço Python personalizada.
Assinatura de função
Uma função de política de serviço SQL toma um único eventVARIANT parâmetro e retorna um VARIANT.
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
Para APIs de modelo em estilo chat e chamadas de ferramentas MCP, a função roda em ambos os pontos de avaliação.
event:type::string Ramificar para diferenciá-los:
-
'request': a fase de entrada (ON CALL), antes do serviço ser invocado. -
'response': a fase de saída (NO RESULTADO), após a resposta do serviço.
Para solicitações de embedding, a função recebe apenas o 'request' evento e lê a entrada de event:data.input. Ele não inspeciona vetores de embedding. As APIs de Respostas também usam event:data.input, então sua presença sozinha não identifica as solicitações de embedding. Use um serviço separado quando uma política precisar se aplicar apenas a embeddings.
O event argumento
event carrega os dados e o contexto de 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' (entrada, EM CHAMADA) ou 'response' (saída, EM RESULTADO). |
event:target |
Todos os serviços | O nome completo do Catálogo do Unity do serviço ao qual a política está anexada (opcional). |
event:context.request_tags |
Serviços de Modelo, Serviços de Provedores de Modelo, Serviços MCP (tools/call) |
Um objeto JSON de chaves de string fornecidas pelo chamador e valores de string. Veja tags de Solicitação. |
event:context.actor.run_as |
Todos os serviços | A identidade executar como a qual a solicitação autoriza. |
event:context.actor.context.is_on_behalf_of |
Todos os serviços |
true quando um agente ou aplicativo age em nome de um usuário (em nome de, ou OBO). Use-o para gravar políticas com reconhecimento de agente que se aplicam somente quando um agente age para um usuário. |
event:context.actor.context.client_id |
Todos os serviços | A ID do cliente OAuth da identidade de atuação, quando presente (chamadas OBO). |
event:context.actor.context.actor_resource |
Todos os serviços | O recurso da identidade de atuação, como um agente, quando presente. |
event:context.actor.context.is_actor_authenticated |
Todos os serviços |
true quando a identidade interina é autenticada como 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, Serviços de Provedor de Modelos | A última mensagem extraída do usuário ou assistente (independente da API) para APIs de modelo em estilo chat. Este campo está ausente para embeddings. Leia event:data.input em vez disso. |
event:context.conversation.conversation |
Serviços de Modelo, Serviços de Provedor de Modelos | Um array de objetos de mensagem neutros em relação ao provedor na janela de conversa configurada para APIs de modelos em estilo chat. Ausente para embeddings. Disponível para funções personalizadas SQL e Python tanto na avaliação de entrada quanto de saída, incluindo quando a janela está definida para um turno. Durante a avaliação de saída, o array contém a janela de conversa da solicitação originadora. |
event:context.conversation.latest_input |
Serviços de Modelo, Serviços de Provedor de Modelos | Ausente para embeddings. Para APIs de modelo em estilo chat, o texto da mensagem do usuário mais recente na conversa completa, mesmo quando a janela configurada exclui essa mensagem. |
event:data |
Serviços de Modelo, Serviços de Provedor de Modelos | O conteúdo completo de solicitação ou resposta. |
event:request_data |
Serviços de Modelo, Serviços de Provedor de Modelos | A solicitação original, disponível durante a fase de saída (NO RESULTADO). |
Note
O acesso ao caminho (event:...) retorna um VARIANT. Converta-o em um tipo escalar antes de compará-lo a um literal (por exemplo, ); caso contrário, event:type::string = 'request'a comparação falhará com um DATATYPE_MISMATCH erro.
Contexto de conversação
Para uma função SQL ou Python personalizada que avalia uma API de modelo em estilo chat, você pode configurar uma janela de conversa. Para qualquer valor configurado, incluindo uma volta, event:context.conversation tem essa forma neutra em relação ao provedor durante a avaliação tanto de entrada quanto de saída. Durante a avaliação de saída, o objeto contém a conversa da solicitação originadora.
{
"conversation": [
{ "role": "user", "content": "First question" },
{ "role": "assistant", "content": "First answer" },
{ "role": "user", "content": "Follow-up question" }
],
"latest_input": "Follow-up question"
}
O conversation array contém a janela configurada.
latest_input contém a mensagem mais recente do usuário da conversa completa, mesmo quando essa mensagem está fora da janela. Se o contexto de conversa multi-turno for desativado para o workspace, toda janela configurada é tratada como um turno.
O gateway preserva event:context.message e event:data, então as funções existentes continuam a receber a única mensagem extraída e a carga útil completa do provedor. O objeto de conversa não é adicionado quando a janela está desconfigurada, para embeddings ou para serviços MCP.
Etiquetas da solicitação
Políticas personalizadas podem avaliar as tags enviadas no Databricks-Ai-Gateway-Request-Tags cabeçalho:
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
Esse suporte se aplica a requisições do Unity Gateway em caminhos onde as políticas de serviço são executadas, incluindo MCP tools/call.
Tags vêm de cabeçalhos de requisições e aparecem event:context junto 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 tag com event:context.request_tags.project::string. Teclas e valores preservam maiúsculas, pontuação e strings vazias. Uma requisição sem o cabeçalho tem um objeto vazio ({}). Ambas as fases de avaliação recebem as mesmas tags de solicitação, incluindo transformações de requisição, tentativas e fallback de modelos.
Por padrão, o tamanho combinado das chaves e valores decodificados é limitado a 10 KiB de dados UTF-8. Também se aplicam limites de tamanho de cabeçalho HTTP. Para exemplos de SDK e REST, veja Marcagem de Solicitações.
Serviços de modelo rejeitam cabeçalhos de tag mal formados ou sobredimensionados. Para requisições MCP tools/call com políticas de serviço aplicáveis, o gateway também rejeita esses cabeçalhos antes de avaliar as políticas, inclusive no modo Log .
As tags são fornecidas pelo chamador e são separadas das etiquetas de serviço e do contexto do ator autenticado. Uma tag sozinha não estabelece identidade ou permissão para usar um projeto. Use dados confiáveis de identidade e autorização ao verificar essas permissões. Veja Exigir um projeto elegível para um exemplo de verificação do valor de uma etiqueta.
As seguintes limitações se aplicam:
- As tags de pedido não são adicionadas automaticamente aos prompts do LLM como juiz. As políticas de serviço externo as recebem, conforme descrito na referência da API de política de serviço externa.
- As aprovações do MCP
ASKnão distinguem tags de solicitação, e os prompts de aprovação não as exibem. Uma aprovação pode ser reutilizada para uma chamada que seria compatível com tags diferentes. UsoALLOWeDENYdecisões para aplicação baseada em tags. Essas decisões são avaliadas em cada solicitação.
Valor de retorno
Uma política SQL personalizada é uma Política de Decisão: ela retorna a VARIANT com um result campo de ALLOW, DENY, ou ASK (insensível a maiúsculas e minúsculas) e um opcional reason. O result valor determina o que acontece:
-
ALLOW: a interação prossegue. -
DENY: Azure Databricks bloqueia a interação. Para APIs de modelo em estilo chat, o chamador recebe uma resposta bem-sucedida (HTTP 200) em vez de um erro. Para aquelas APIs em um Serviço de Modelo ou Serviço de Provedor de Modelo, o turno assistente reporta o bloco, com oreasonem um objeto de nível superiordatabricks_service_policy. Uma negação de embedding retorna HTTP 400 para toda a solicitação antes que o modelo seja executado. Em um Serviço MCP, a resposta é um erro JSON-RPC com oreasonemerror.message. -
ASK: em um Serviço MCP, a solicitação pausa para aprovação do usuário antes que a ferramenta seja executada. Se uma função de política personalizada retornaASKpara um Serviço Modelo ou Serviço de Provedor Modelo, o Azure Databricks bloqueia a solicitação ou resposta porque esses serviços não podem solicitar aprovação do usuário.
Compile o resultado com named_struct e embrulhe-o para que to_variant_object a função retorne um VARIANTcampo , mantendo result e reason como de nível superior. Um bare named_struct retorna um STRUCTe CAST(... AS VARIANT) não tem suporte.
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 futuro:
to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))
Note
Um campo que não existe no VARIANT parâmetro é lido como NULL, como no acesso SQL VARIANT padrão. Uma comparação que lê um campo ausente, como =, , ou IN, gera um erro e resulta em DENY<. Isso impede que uma política permita uma interação quando os campos esperados estão ausentes. Para lidar com um campo que pode estar faltando, use uma função de tratamento nulo como ISNULL ou COALESCE. Veja Funções de manuseio nulo.
Funções de políticas em Python
Uma função de política em Python assume dois VARIANT parâmetros, event e config, e retorna um VARIANT:
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT,
config VARIANT
)
RETURNS VARIANT
LANGUAGE PYTHON
ENVIRONMENT (environment_version = '6')
AS $$
<function body>
$$;
-
eventtem os campos listados em Oeventargumento. No Python, converta comtoPython()e leia os mesmos campos que as chaves do dicionário. Por exemplo,event:context.tool.nameem SQL éevent_value.get("context", {}).get("tool", {}).get("name")em Python. -
configcontém as opções armazenadas no anexo da política, ou um objeto vazio quando não tem nenhum. A função deve declará-lo, mesmo que não o utilize. - A função retorna a
VARIANTque contém umdecisionobjeto, com umresultdeALLOW,DENY, ouASK(indiferente a maiúsculas e minúsculas) e um opcionalreason:
import json
def policy_decision(result, reason=""):
return type(event).parseJson(json.dumps({"decision": {"result": result, "reason": reason}}))
event_value = event.toPython() if hasattr(event, "toPython") else event
if event_value.get("type") == "request" and "confidential" in str(event_value.get("context", {}).get("message", "")).lower():
return policy_decision("DENY", "Requests about confidential projects are not allowed.")
return policy_decision("ALLOW")
As restrições SQL suportadas não se aplicam a funções Python, que rodam como UDFs Python do Unity Catalog e podem usar a biblioteca padrão Python e dependências declaradas. Uma exceção não tratada, como um KeyError de leitura de um campo ausente com [], nega a interação. Leia campos opcionais com get(). Para requisitos, dependências, credenciais de serviço e limitações, veja Escrever uma política de serviço Python personalizada.
SQL suportado
Azure Databricks transpila o corpo da política para CEL e o avalia em runtime, de modo que o corpo da função dá suporte apenas a um subconjunto restrito do SQL. O Azure Databricks rejeita uma função ou construto não suportado quando você 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 de Teste , verifique o corpo apenas como SQL. O Azure Databricks verifica a compatibilidade com CEL quando você anexa a política, então anexe a política para confirmar que o corpo é suportado.
| Categoria | Com suporte no corpo da política |
|---|---|
| Operators | Operadores de comparação, lógicos e aritméticos; \|\|, INe LIKEIS [NOT] NULL |
| Fluxo de controle |
CASE e IF |
| Conversões |
CAST para INT/BIGINT, DOUBLE/FLOAT, STRING, ou BOOLEAN; o :: operador |
| Acesso a dados | Acesso ao caminho VARIANT/JSON |
| Funções de cadeia de caracteres |
CONCAT, LENGTH, UPPER, , LOWER, SUBSTRING, , STARTSWITHENDSWITHLTRIMREPLACERTRIMTRIMCHAR_LENGTHCONTAINS |
| Outras funções |
COALESCE, NULLIF, IFNULL, NVL, ABS, , MOD, ISNULL, , ISNOTNULL, NAMED_STRUCT, TO_VARIANT_OBJECT |
Não suportado:ai_query, subconsultas, BETWEEN, funções agregadas, lambdas / EXISTS, e variadic CONCAT ou COALESCE.
Funções de manuseio nulo
COALESCE, IFNULL, NVL, ISNULL, e ISNOTNULL falham na validação CEL quando seu primeiro argumento é lançado para STRING dentro da chamada, por event:context.message::STRINGexemplo. Passe o campo de evento como um VARIANT valor em vez disso. Para COALESCE, IFNULL, e NVL, lança o resultado:
| Falha na validação do CEL | Passa pela 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 recurso pode ser literal, como '', ou outro campo de evento.
COALESCE aceita exatamente dois argumentos.
NULLIF também falha na validação CEL quando seu primeiro argumento é lançado para STRING, por exemplo NULLIF(event:context.message::STRING, 'n/a').
Como um campo ausente é lido como NULL, essas funções podem lidar com campos opcionais. Por exemplo, uma solicitação sem uma project tag não event:context.request_tags.project tem campo, então a seguinte condição é verdadeira:
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''