Pular para o conteúdo principal

Referência da API da política de serviço externo

info

Beta

Esse recurso está em Beta. Os administradores de 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.

Quando um cliente anexa uma política de serviço externo a um serviço, o Unity Gateway chama o endpoint HTTP de um fornecedor de guardrail em cada interação governada e aplica o veredito que o endpoint retorna. Esta página descreve o contrato que o endpoint implementa: a solicitação que o Databricks envia, a resposta que espera e como ele lida com cada resposta.

Use esta página para criar um endpoint que os clientes podem usar com políticas de serviço externas ou para verificar se o endpoint de um fornecedor é compatível. Para a configuração do cliente, consulte Impor uma barreira de proteção de parceiro com uma política de serviço externa.

Como funciona​

Em cada interação governada, o Databricks envia uma solicitação POST com um corpo JSON para o endpoint. O endpoint inspeciona o conteúdo e retorna ALLOW, DENY ou, para uma chamada de ferramenta MCP, ASK, e o Databricks impõe o veredito.

Um endpoint pode atender muitos clientes e políticas. Um cliente escolhe o comportamento que deseja com a configuração de política, que o Databricks passa para o endpoint em cada solicitação.

Requisitos de endpoint​

O endpoint deve:

  • Aceitar POST solicitações com um corpo JSON no host e no caminho que o cliente configura na conexão.
  • Aceitar autenticação OAuth machine-to-machine (M2M). O cliente configura um ID de cliente, um segredo de cliente, seu endpoint de token e escopos opcionais na conexão. O Databricks obtém um access token do seu endpoint de token e o envia no cabeçalho Authorization de cada solicitação. Seu endpoint de token deve retornar tokens no formato que a especificação OAuth 2.0 define. Consulte Serviços externos devem estar em conformidade com as especificações OAuth 2.0.
  • Use HTTPS. O Databricks não chama um endpoint sobre HTTP simples.
  • Responda em até 5 segundos. O Databricks nega a interação quando o endpoint não responde a tempo.
  • Retorne HTTP 200 com um veredito JSON para cada decisão, incluindo um bloco, em um corpo de resposta não maior que 64 KB.

Se o endpoint suportar mais de um comportamento, como diferentes perfis de detecção, informe aos clientes o que inserir como a configuração de política.

Solicitado​

O Databricks envia cada avaliação como uma solicitação HTTP para o host e caminho da conexão. O caminho é / quando a conexão não tem nenhum.

HTTP
POST /<path> HTTP/1.1
Host: <host>
Authorization: Bearer <access-token>
Content-Type: application/json

O corpo é um objeto JSON com dois membros:

JSON
{
"event": {},
"config": {}
}
  • event é a interação sob avaliação. Consulte O objeto event.
  • config contém as opções da política, incluindo a configuração da política do cliente. Consulte O objeto config.

O objeto event​

Ignore os campos event que você não reconhece.

campo

Tipo

Descrição

type

String

A interação e a fase: tool_call, tool_result, model_call ou model_result. Presente em todos os eventos. Consulte Tipos de evento.

target

String

O identificador do serviço governado. Os eventos MCP usam o nome de três níveis no Unity Catalog, por exemplo main.default.github_mcp. Eventos de modelo usam o ID imutável do serviço. Presente em todos os eventos.

data

Objeto

O conteúdo em avaliação. A forma depende de type. Presente em todos os eventos.

request_data

Objeto

A solicitação original, para que você possa julgar um resultado no contexto de sua solicitação. Presente somente em tool_result e model_result.

api_type

String

O formato da API de data e request_data. Presente apenas em model_call e model_result. Consulte tipos de API.

trace_id

String

O ID de rastreamento OpenTelemetry da solicitação governada. Use-o para corresponder uma avaliação em seus logs à solicitação. Presente apenas quando a solicitação tem um rastreamento, portanto não o exija.

context.request_tags

Objeto com valores de strings

Tags de solicitação fornecidas pelo chamador. Presente em todos os eventos. Um objeto vazio significa que o chamador não forneceu tags.

campo

Tipo

Descrição

type

String

A interação e a fase: tool_call, tool_result, model_call ou model_result. Presente em todos os eventos. Consulte Tipos de evento.

target

String

O identificador do serviço governado. Os eventos MCP usam o nome de três níveis no Unity Catalog, por exemplo main.default.github_mcp. Eventos de modelo usam o ID imutável do serviço. Presente em todos os eventos.

data

Objeto

O conteúdo em avaliação. A forma depende de type. Presente em todos os eventos.

request_data

Objeto

A solicitação original, para que você possa julgar um resultado no contexto de sua solicitação. Presente somente em tool_result e model_result.

api_type

String

O formato da API de data e request_data. Presente apenas em model_call e model_result. Consulte tipos de API.

trace_id

String

O ID de rastreamento OpenTelemetry da solicitação governada. Use-o para corresponder uma avaliação em seus logs à solicitação. Presente apenas quando a solicitação tem um rastreamento, portanto não o exija.

context.request_tags

Objeto com valores de strings

Tags de solicitação fornecidas pelo chamador. Presente em todos os eventos. Um objeto vazio significa que o chamador não forneceu tags.

O evento não inclui a identidade autenticada do usuário, agente ou aplicativo que fez a chamada.

O objeto context contém apenas request_tags. Ambas as fases recebem as mesmas tags fornecidas pelo chamador, preservando maiúsculas e minúsculas, pontuação e strings vazias. As tags permanecem separadas de data e request_data, inclusive depois que outra política transforma esses corpos.

Se o Databricks não puder fornecer as tags fornecidas pelo chamador, ele tratará a avaliação como uma falha sem chamar o endpoint ou substituir um objeto vazio. No modo Enforce, isso nega a interação, conforme descrito em Como o Databricks lida com cada resposta. No modo Log, a falha é registrada, mas não bloqueia a interação. Os avaliadores que exigem tags específicas devem retornar um veredito DENY com HTTP 200 quando uma solicitação os omite.

As tags são reivindicações fornecidas pelo chamador. Use uma verificação de autorização confiável separada antes de usar uma tag para selecionar um tenant, projeto ou política menos restritiva. Trate os valores de tags como dados ao construir prompts ou query. Não inclua valores de tag sensíveis em motivos de veredicto ou logs. As aprovações de MCP não estão vinculadas a tags e podem ser reutilizadas em chamadas com tags diferentes.

Tipos de evento​

type

Serviço e fase

data

request_data

tool_call

Serviço MCP, antes da execução da ferramenta

{"name": "<tool>", "arguments": {...}}

Não presente

tool_result

Serviço MCP, após a execução da ferramenta

Resultado da ferramenta

{"name": "<tool>", "arguments": {...}}, a chamada original

model_call

Serviço de Modelo ou Serviço de Provedor de Modelo, antes de o modelo ser chamado

O corpo da solicitação do modelo completo, no formato nomeado por api_type

Não presente

model_result

Serviço de modelo ou serviço de provedor de modelo, após o modelo responder

O corpo completo da resposta do modelo, no formato nomeado por api_type

O corpo completo da solicitação do modelo

type

Serviço e fase

data

request_data

tool_call

Serviço MCP, antes da execução da ferramenta

{"name": "<tool>", "arguments": {...}}

Não presente

tool_result

Serviço MCP, após a execução da ferramenta

Resultado da ferramenta

{"name": "<tool>", "arguments": {...}}, a chamada original

model_call

Serviço de Modelo ou Serviço de Provedor de Modelo, antes de o modelo ser chamado

O corpo da solicitação do modelo completo, no formato nomeado por api_type

Não presente

model_result

Serviço de modelo ou serviço de provedor de modelo, após o modelo responder

O corpo completo da resposta do modelo, no formato nomeado por api_type

O corpo completo da solicitação do modelo

Para APIs de modelo estilo chat, um corpo de solicitação de modelo inclui as mensagens na solicitação, como o prompt do sistema e turnos anteriores da conversa. Se o cliente definir uma janela de conversa para a política, o corpo pode conter apenas as mensagens mais recentes, então não presuma que a conversa completa esteja presente.

Tipos de API​

Os eventos de modelo carregam corpos de solicitação e resposta no formato de API usado pela rota do modelo. O Databricks não os converte para um formato comum. O campo api_type nomeia o formato:

api_type

Formato

mlflow/v1/chat/completions

Completions de chat do Databricks, compatíveis com Completions de Chat da OpenAI

mlflow/v1/embeddings

Embeddings do Databricks

mlflow/v1/responses

Respostas abertas da Databricks

openai/v1/chat/completions

Conclusões de chat do OpenAI

openai/v1/embeddings

Incorporações OpenAI

openai/v1/responses

Respostas OpenAI

anthropic/v1/messages

Mensagens do Anthropic

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

Conclusões de bate-papo de cursor

api_type

Formato

mlflow/v1/chat/completions

Completions de chat do Databricks, compatíveis com Completions de Chat da OpenAI

mlflow/v1/embeddings

Embeddings do Databricks

mlflow/v1/responses

Respostas abertas da Databricks

openai/v1/chat/completions

Conclusões de chat do OpenAI

openai/v1/embeddings

Incorporações OpenAI

openai/v1/responses

Respostas OpenAI

anthropic/v1/messages

Mensagens do Anthropic

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

Conclusões de bate-papo de cursor

As solicitações do Codex usam o formato de Respostas, de modo que seus eventos transportam api_type openai/v1/responses ou mlflow/v1/responses, dependendo da rota do modelo. codex/v1/responses nomeia o endpoint, portanto, ele está ausente desta lista de formatos de evento.

Para um model_call de embedding, data.input contém a entrada da solicitação. Para solicitações de embedding, as políticas externas recebem apenas eventos model_call, sem eventos model_result ou vetores. Uma redação aplicada em uma classificação de entrada anterior é visível para políticas posteriores. Eventos de entrada de embedding mantêm o formato JSON completo e não são convertidos em mensagens de chat. Consulte Guardrails de entrada de embedding.

Para cobertura e exclusões da API de modelo, consulte APIs de modelo suportadas.

O Unity Gateway pode adicionar tipos de API à medida que suporta mais APIs. Trate um api_type que você não reconhece como conteúdo que você não pode analisar e retorne um veredito deliberado para ele, como DENY.

O objeto config​

config mantém as opções da política como strings. Não inclui a conexão ou o caminho.

campo

Tipo

Descrição

policy_config

String

A configuração de política exatamente como o cliente a inseriu, como um objeto JSON passado em strings. Analise a string como JSON, por exemplo "{\"profile\": \"strict\"}". O Databricks não lê esse valor. Não está presente quando o cliente deixa vazio.

phases

String

As fases em que a política entra em execução: pre_call, post_call ou pre_call,post_call.

campo

Tipo

Descrição

policy_config

String

A configuração de política exatamente como o cliente a inseriu, como um objeto JSON passado em strings. Analise a string como JSON, por exemplo "{\"profile\": \"strict\"}". O Databricks não lê esse valor. Não está presente quando o cliente deixa vazio.

phases

String

As fases em que a política entra em execução: pre_call, post_call ou pre_call,post_call.

config pode incluir outras opções de política. Ignore as key que você não reconhece.

Exemplos de solicitação​

Uma chamada de ferramenta MCP, antes da execução da ferramenta:

JSON
{
"event": {
"type": "tool_call",
"target": "main.default.github_mcp",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"context": { "request_tags": { "project": "p-1042" } },
"data": {
"name": "create_issue",
"arguments": { "repo": "acme/website", "title": "Bug: checkout returns 500" }
}
},
"config": {
"policy_config": "{\"profile\": \"strict\"}",
"phases": "pre_call"
}
}

Um resultado de ferramenta MCP, após a execução da ferramenta:

JSON
{
"event": {
"type": "tool_result",
"target": "main.default.github_mcp",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"context": { "request_tags": { "project": "p-1042" } },
"data": { "content": [{ "type": "text", "text": "Issue #4213 created" }] },
"request_data": { "name": "create_issue", "arguments": { "repo": "acme/website" } }
},
"config": {
"phases": "pre_call,post_call"
}
}

Uma solicitação de modelo, antes que o modelo seja chamado:

JSON
{
"event": {
"type": "model_call",
"target": "123e4567-e89b-42d3-a456-426614174000",
"api_type": "mlflow/v1/chat/completions",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"context": { "request_tags": { "project": "p-1042" } },
"data": {
"messages": [
{ "role": "system", "content": "You are a support agent." },
{ "role": "user", "content": "My card number is 4111 1111 1111 1111. Please refund me." }
],
"max_tokens": 512
}
},
"config": {
"phases": "pre_call"
}
}

Uma resposta do modelo, depois que o modelo responder:

JSON
{
"event": {
"type": "model_result",
"target": "123e4567-e89b-42d3-a456-426614174000",
"api_type": "mlflow/v1/chat/completions",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"context": { "request_tags": { "project": "p-1042" } },
"data": { "choices": [{ "message": { "role": "assistant", "content": "Here is your refund link." } }] },
"request_data": { "messages": [{ "role": "user", "content": "Please refund me." }] }
},
"config": {
"phases": "post_call"
}
}

Resposta​

Retornar HTTP 200 com um corpo JSON:

JSON
{
"result": "DENY",
"reason": "The message contains a payment card number."
}

campo

Tipo

Descrição

result

String

Obrigatório. ALLOW, DENY ou ASK. O valor não diferencia maiúsculas de minúsculas. Retorne ASK apenas para um evento tool_call. Veja Manter uma chamada de ferramenta para aprovação.

reason

String

Opcional. Em DENY, o Databricks o retorna ao chamador. Quando ele está vazio ou ausente, o chamador recebe o motivo default: "Acesso negado: esta solicitação não é permitida por uma política nesse serviço."

campo

Tipo

Descrição

result

String

Obrigatório. ALLOW, DENY ou ASK. O valor não diferencia maiúsculas de minúsculas. Retorne ASK apenas para um evento tool_call. Veja Manter uma chamada de ferramenta para aprovação.

reason

String

Opcional. Em DENY, o Databricks o retorna ao chamador. Quando ele está vazio ou ausente, o chamador recebe o motivo default: "Acesso negado: esta solicitação não é permitida por uma política nesse serviço."

Retorne um bloco como um veredito DENY com HTTP 200, não como um erro HTTP. O Databricks trata um erro HTTP como uma avaliação com falha, portanto, nega a interação, mas o chamador não vê o seu motivo.

Políticas de serviço externo não podem redigir ou reescrever conteúdo, portanto, não retorne um payload modificado.

Manter uma chamada de ferramenta para aprovação​

Em um evento tool_call, retorne ASK para manter a chamada da ferramenta até que o usuário a aprove. Se o usuário aprovar, o Databricks faz a execução da chamada da ferramenta. Retornar ASK apenas para um evento tool_call:

  • Em um evento tool_result, ASK não bloqueia. O resultado é processado como se você tivesse retornado ALLOW. Para bloquear um resultado, retorne DENY.
  • Em um evento model_call ou model_result, o Databricks bloqueia a interação porque os Serviços de Modelo e os Serviços de Provedor de Modelo não podem solicitar aprovação ao usuário.

Como o Databricks lida com cada resposta​

No modo de imposição, as políticas de serviço externo falham fechadas. O Databricks nega a interação sempre que não consegue ler um veredito do endpoint:

Resposta

O que o Databricks faz

result é ALLOW

Permite a interação.

result é DENY

Recusa a interação e retorna o seu reason ou o motivo default.

result é ASK

Em um tool_call, mantém a chamada de ferramenta até que o usuário a aprove. Em um tool_result, permite o resultado. Em um evento de modelo, nega a interação.

result está faltando, está vazio, não é uma string ou tem um valor não reconhecido

Nega a interação.

O corpo não é um JSON válido ou tem um membro error de nível superior

Nega a interação.

O corpo é maior que 64 KB

Nega a interação.

O status HTTP não é 2xx

Nega a interação.

Sem resposta dentro de 5 segundos

Nega a interação.

A conexão falha

Nega a interação.

Resposta

O que o Databricks faz

result é ALLOW

Permite a interação.

result é DENY

Recusa a interação e retorna o seu reason ou o motivo default.

result é ASK

Em um tool_call, mantém a chamada de ferramenta até que o usuário a aprove. Em um tool_result, permite o resultado. Em um evento de modelo, nega a interação.

result está faltando, está vazio, não é uma string ou tem um valor não reconhecido

Nega a interação.

O corpo não é um JSON válido ou tem um membro error de nível superior

Nega a interação.

O corpo é maior que 64 KB

Nega a interação.

O status HTTP não é 2xx

Nega a interação.

Sem resposta dentro de 5 segundos

Nega a interação.

A conexão falha

Nega a interação.

Os clientes não podem configurar uma política de serviço externo no modo de imposição para permitir o tráfego quando o endpoint falha. No modo de log, o Databricks registra vereditos e falhas de avaliação, mas não os aplica, portanto, eles não bloqueiam a interação.

Quando o Databricks chama o endpoint​

  • O Databricks chama o Endpoint uma vez para cada fase em que a política está em execução: antes de o serviço ser chamado, depois que ele responde ou ambos. Uma política com execução em ambas as fases envia duas solicitações para uma interação de modelo estilo chat ou chamada de ferramenta MCP. Para embeddings, apenas a fase de entrada entra em execução.
  • Quando o cliente anexa a política no modo Log , o Databricks ainda chama o endpoint e registra seu veredito, mas não o aplica.
  • Uma DENY de outra política cuja execução ocorre antes da política de serviço externo pode interromper a interação antes que o Databricks chame o seu Endpoint. Consulte Ordem de avaliação.

Manipulação de dados​

Cada solicitação carrega o conteúdo do cliente: corpos de solicitação e resposta do modelo, incluindo prompts de sistema e mensagens anteriores, e nomes, argumentos e resultados de ferramentas MCP. Trate-o como dados do cliente e documente para os clientes o que seu endpoint armazena, por quanto tempo e onde ele processa o conteúdo.

Cada avaliação externa envia as tags fornecidas pelo chamador ao avaliador, inclusive no modo Log. As tags podem conter identificadores confidenciais. Revise esta divulgação de metadados com o cliente ao configurar um avaliador externo.

By default, o tamanho combinado das keys e valores de tags decodificados é limitado a 10 KiB de dados UTF-8. Os limites de tamanho do cabeçalho HTTP também se aplicam. Os cabeçalhos de tag malformados ou muito grandes são rejeitados antes da avaliação externa: as solicitações de modelo retornam um erro HTTP 400 com o código INVALID_PARAMETER_VALUE, e as solicitações MCP tools/call com políticas de serviço aplicáveis retornam HTTP 200 com um erro JSON-RPC POLICY_DENIED (-32003). Esta validação também se aplica no modo Log. Consulte Solicitar tags em políticas de serviço.

Testar seu endpoint​

Antes que os clientes usem seu endpoint, envie a ele uma solicitação de amostra e verifique se ele retorna HTTP 200 com um result de ALLOW, DENY ou ASK em menos de 5 segundos:

Bash
curl -X POST "https://api.example.com/ai-security/v1" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"event": {"type": "tool_call", "target": "main.default.github_mcp", "data": {"name": "create_issue", "arguments": {"repo": "acme/website"}}, "context": {"request_tags": {, "config": {"policy_config": "{\"profile\": \"strict\"}", "phases": "pre_call"}}'

Para testar o fluxo completo, anexe uma política de serviço externo que usa seu endpoint a um serviço em um workspace do Databricks, no modo Log , e revise os veredictos registrados na tabela de rastreamento unificada. Consulte Impor um guardrail de parceiro com uma política de serviço externo.

Os passos seguintes​