Referência da função da política de serviço
Beta
Este recurso está em Beta. Os administradores do Workspace podem controlar o acesso a esse recurso na página Prévias optando pela prévia de Políticas de Serviço do Unity Gateway . Consulte Gerenciar prévias no nível do workspace.
Uma função de política de serviço personalizada é uma função definida pelo usuário (UDF) 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 ponta a ponta, consulte Criar uma política SQL.
Para funções de política Python, consulte Funções de política Python e Escrever uma política de serviço Python personalizada.
Assinatura de função
Uma função de política de serviço SQL usa um parâmetro event VARIANT e retorna um VARIANT.
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
Para APIs de modelos no estilo de chat e chamadas de ferramentas MCP, a função tem execução em ambos os pontos de avaliação. Faça branch com base em event:type::string para diferenciá-los:
'request': a fase de entrada (ON CALL), antes que o serviço seja invocado.'response': a fase de saída (ON RESULT), após a resposta do serviço.
Para solicitações de incorporação, a função recebe apenas o evento 'request' e lê a entrada de event:data.input. Não inspeciona vetores de incorporação. As APIs de resposta também usam event:data.input, portanto, sua presença por si só não identifica solicitações de incorporação. Use um serviço separado quando uma política precisar ser aplicada apenas a incorporações.
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 |
|---|---|---|
| Todos os serviços | A fase: |
| Todos os serviços | O nome completo do Unity Catalog do serviço ao qual a política está anexada (opcional). |
| Model Serviços, Model Provider Serviços, MCP Serviços ( | Um objeto JSON de keys de string e valores de strings fornecidos pelo chamador. Consulte Tags de solicitação. |
| Todos os serviços | A identidade de execução com a qual a solicitação é autorizada. |
| Todos os serviços |
|
| Todos os serviços | O ID do cliente OAuth da identidade que está atuando, quando presente (chamadas OBO). |
| Todos os serviços | O recurso da identidade em ação, como um agente, quando presente. |
| Todos os serviços |
|
| Serviços MCP | A ferramenta que está sendo chamada e seus argumentos (por exemplo, |
| Serviços de Modelo, Serviços de Provedor de Modelo | A última mensagem de usuário ou assistente extraída (agnóstica a APIs) para APIs de modelo em estilo de chat. Este campo está ausente para embeddings. Leia |
| Serviços de Modelo, Serviços de Provedor de Modelo | Uma matriz de objetos de mensagem neutros ao provedor na janela de conversa configurada para APIs de modelo em estilo de chat. Ausente para embeddings. Disponível para funções personalizadas de SQL e Python durante a avaliação de entrada e saída, incluindo quando a janela é definida para um turno. Durante a avaliação de saída, a matriz contém a janela de conversa da solicitação de origem. |
| Serviços de Modelo, Serviços de Provedor de Modelo | Ausente para embeddings. Para APIs de modelos estilo chat, o texto da mensagem de usuário mais recente em toda a conversa, mesmo quando a janela configurada exclui essa mensagem. |
| Serviços de Modelo, Serviços de Provedor de Modelo | O payload completo de solicitação ou resposta. |
| Serviços de Modelo, Serviços de Provedor de Modelo | A solicitação original, disponível durante a fase de saída (ON RESULT). |
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.
Contexto da conversa
Para uma função SQL ou Python personalizada que avalia uma API de modelo de estilo de bate-papo, você pode configurar uma janela de conversa. Para qualquer valor configurado, incluindo um turno, event:context.conversation tem essa forma neutra do provedor durante a avaliação de entrada e saída. Durante a avaliação de saída, o objeto contém a conversa da solicitação original.
{
"conversation": [
{ "role": "user", "content": "First question" },
{ "role": "assistant", "content": "First answer" },
{ "role": "user", "content": "Follow-up question" }
],
"latest_input": "Follow-up question"
}
O array conversation contém a janela configurada. latest_input contém a mensagem de usuário mais recente da conversa completa, mesmo quando essa mensagem está fora da janela. Se o contexto de conversa de várias turnos estiver desabilitado para o workspace, cada janela configurada é tratada como um turno.
O gateway preserva event:context.message e event:data, para que as funções existentes continuem a receber a única mensagem extraída e o payload completo do provedor. O objeto de conversa não é adicionado quando a janela não está definida, para embeddings ou para Serviços MCP.
Solicitar tags
Políticas personalizadas podem avaliar as tags enviadas no cabeçalho Databricks-Ai-Gateway-Request-Tags:
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
Esse suporte se aplica a solicitações do Unity Gateway em caminhos onde as políticas de serviço estão em execução, incluindo o MCP tools/call.
As tags vêm dos headers de requisição e aparecem em event:context junto com outros metadados de política. event:data e event:request_data contêm corpos de payload.
event:context.request_tags is an object inside the event VARIANT, with string keys and string values, logically MAP<STRING, STRING>. Read a tag with event:context.request_tags.project::string. Keys and values preserve case, punctuation, and empty strings. A request without the header has an empty object ({}). Both evaluation phases receive the same request tags, including through request transformações, retries, and model fallback.
Por default, o tamanho combinado das chaves e dos valores decodificados é limitado a 10 KiB de dados UTF-8. Limites de tamanho de cabeçalho HTTP também se aplicam. Para exemplos de SDK e REST, consulte tag de solicitação.
Os serviços de modelo rejeitam cabeçalhos de tag malformados ou grandes demais. Para solicitações do 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 .
Tags are supplied by the caller and are separate from serviço tags and authenticated actor context. A tag alone doesn't establish identity or permission to use a project. Use trusted identity and authorization data when checking those permissions. See Require an eligible project for an example of checking a tag value.
Aplicam-se as seguintes limitações:
- As tags de solicitação não são adicionadas automaticamente aos prompts de LLM-as-a-judge. As políticas de serviço externo as recebem, conforme descrito na referência de API de política de serviço externo.
- 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 correspondente, mas com tags diferentes. Use as decisões deALLOWeDENYpara a imposiçã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 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: O Databricks bloqueia a interação. Para APIs de modelo no estilo de chat, o chamador recebe uma resposta bem-sucedida (HTTP 200) em vez de um erro. Para essas APIs em um serviço de modelo ou serviço de provedor de modelo, o turno do assistente relata o bloqueio, com oreasonem um objeto de nível superiordatabricks_service_policy. Uma negação de incorporação retorna HTTP 400 para toda a solicitação antes da execução do modelo. 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 da execução da ferramenta. Se uma função de política personalizada retornarASKpara um Serviço de Modelo ou Serviço de Provedor de Modelo, o Databricks bloqueia a solicitação ou resposta porque esses serviços não podem pedir aprovação ao usuário.
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.
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:
to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))
Um campo que não existe no parâmetro VARIANT é lido como NULL, como no acesso padrão SQL VARIANT. Uma comparação que lê um campo ausente, como =, < ou IN, gera um erro e resulta em DENY. Isso evita que uma política permita uma interação quando os campos esperados estão ausentes. Para lidar com um campo que pode estar ausente, use uma função de tratamento de nulo como ISNULL ou COALESCE. Veja Funções de tratamento de nulo.
Funções de política Python
Uma função de política Python recebe dois parâmetros VARIANT, 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 O argumentoevent. Em Python, converta-o comtoPython()e leia os mesmos campos como chaves de dicionário. Por exemplo,event:context.tool.nameem SQL éevent_value.get("context", {}).get("tool", {}).get("name")em Python.configmantém as opções armazenadas no anexo da política ou um objeto vazio quando não há nenhuma. A função deve declará-lo, mesmo que não o utilize.- A função retorna um
VARIANTque contém um objetodecision, com umresultdeALLOW,DENYouASK(insensível a maiúsculas e minúsculas) e umreasonopcional:
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 de SQL compatível não se aplicam às funções Python, que são executadas em execução como UDFs Python do Unity Catalog e podem usar a biblioteca padrão do Python e dependências declaradas. Uma exceção não tratada, como um KeyError ao ler um campo ausente com [], nega a interação. Leia campos opcionais com get(). Para requisitos, dependências, credenciais de serviço e limitações, consulte Escrever uma política de serviço Python personalizada.
SQL compatível
O Databricks transpila o corpo da política para CEL e o avalia em runtime; portanto, o corpo da função suporta apenas um subconjunto restrito de SQL. O Databricks rejeita uma função ou constructo 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 fechada (DENY) na avaliação. Criar a função e executá-la em Test function verifica o corpo apenas como SQL. O Databricks verifica a compatibilidade de CEL quando você anexa a política, portanto, anexe a política para confirmar que o corpo é suportado.
Categoria | Compatível no corpo da política |
|---|---|
Operadores | Operadores de comparação, lógicos e aritméticos; |
Fluxo de controle |
|
Conversões |
|
Acesso aos dados | VARIANTE / acesso ao caminho JSON |
Funções de strings |
|
Outras funções |
|
Não suportado: ai_query, subqueries, BETWEEN, funções de agregação, lambdas / EXISTS e CONCAT ou COALESCE variádicos.
Funções de tratamento nulo
COALESCE, IFNULL, NVL, ISNULL e ISNOTNULL falham na validação CEL quando seu primeiro argumento é convertido para STRING dentro da chamada, por exemplo event:context.message::STRING. Passe o campo de evento como um valor VARIANT em vez disso. Para COALESCE, IFNULL e NVL, converta o resultado:
Falha na validação CEL | Passa pela validação CEL |
|---|---|
|
|
|
|
|
|
|
|
|
|
O fallback pode ser um literal, como '', ou outro campo de evento. COALESCE aceita exatamente dois argumentos.
NULLIF também falha na validação CEL quando seu primeiro argumento é convertido 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 tag project não tem um campo event:context.request_tags.project, portanto, a seguinte condição é verdadeira:
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''