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 SQL personalizada é uma função definida pelo usuário (UDF) SQL registrada no Unity Catalog que o Databricks avalia a cada interação com o serviço ao qual está associada. Esta página é a referência de campos e sintaxe para essas funções. Para ver o procedimento de ponta a ponta, consulte Criar uma política SQL.

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 de entrada ( ON CALL ), antes que o serviço seja invocado.
• 'response': a fase de saída ( ON RESULT ), após o serviço responder.

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' (entrada, ON CALL) ou 'response' (saída, ON RESULT).
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.request_tags	Model Serviços, Model Provider Serviços, MCP Serviços (tools/call)	Um objeto JSON de keys de string e valores de strings fornecidos pelo chamador. Consulte Tags de solicitação.
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, Serviços de Provedor 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, Serviços de Provedor de Modelo	O payload completo de solicitação ou resposta.
event:request_data	Serviços de Modelo, Serviços de Provedor de Modelo	A solicitação original, disponível durante a fase de saída (ON RESULT).

campo	Aplica-se a	Descrição
event:type	Todos os serviços	A fase: 'request' (entrada, ON CALL) ou 'response' (saída, ON RESULT).
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.request_tags	Model Serviços, Model Provider Serviços, MCP Serviços (tools/call)	Um objeto JSON de keys de string e valores de strings fornecidos pelo chamador. Consulte Tags de solicitação.
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, Serviços de Provedor 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, Serviços de Provedor de Modelo	O payload completo de solicitação ou resposta.
event:request_data	Serviços de Modelo, Serviços de Provedor de Modelo	A solicitação original, disponível durante a fase de saída (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.

Solicitar tags

Políticas personalizadas podem avaliar as tags enviadas no cabeçalho Databricks-Ai-Gateway-Request-Tags:

HTTP

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 incluídas em eventos enviados a provedores de políticas externos nem adicionadas automaticamente aos prompts de LLM-como-juiz.
• As aprovações do MCP ASK nã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 de ALLOW e DENY para a imposição baseada em tags. Essas decisões são avaliadas em cada solicitação.

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: O Databricks bloqueia a interação. Em vez de um erro, o chamador recebe uma resposta bem-sucedida (HTTP 200) cujo turno do assistente relata o bloqueio, com o reason em um objeto databricks_service_policy de nível superior.
• ASK: em um Serviço MCP, a solicitação pausa para aprovação do usuário antes que a ferramenta seja executada. Se uma política de SQL ou Python personalizada retornar ASK para um Serviço de Modelo ou Serviço de Provedor de Modelo, o Databricks bloqueará a solicitação ou a resposta porque esses serviços não podem solicitar a aprovação do 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.

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

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