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

info

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 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

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.

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; ||, 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.

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
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)

Falha na validação 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 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:

SQL

CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''

Relacionado

• Políticas de serviço para recursos protegíveis de IA
• Crie e anexe uma política de serviço