Referência da API da política de serviço externo
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
POSTsolicitaçõ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
Authorizationde 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
200com 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.
POST /<path> HTTP/1.1
Host: <host>
Authorization: Bearer <access-token>
Content-Type: application/json
O corpo é um objeto JSON com dois membros:
{
"event": {},
"config": {}
}
eventé a interação sob avaliação. Consulte O objetoevent.configcontém as opções da política, incluindo a configuração da política do cliente. Consulte O objetoconfig.
O objeto event
Ignore os campos event que você não reconhece.
campo | Tipo | Descrição |
|---|---|---|
| String | A interação e a fase: |
| String | O identificador do serviço governado. Os eventos MCP usam o nome de três níveis no Unity Catalog, por exemplo |
| Objeto | O conteúdo em avaliação. A forma depende de |
| Objeto | A solicitação original, para que você possa julgar um resultado no contexto de sua solicitação. Presente somente em |
| String | O formato da API de |
| 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. |
| 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
| Serviço e fase |
|
|
|---|---|---|---|
| Serviço MCP, antes da execução da ferramenta |
| Não presente |
| Serviço MCP, após a execução da ferramenta | Resultado da ferramenta |
|
| 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 | Não presente |
| 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 | 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:
| Formato |
|---|---|
| Completions de chat do Databricks, compatíveis com Completions de Chat da OpenAI |
| Embeddings do Databricks |
| Respostas abertas da Databricks |
| Conclusões de chat do OpenAI |
| Incorporações OpenAI |
| Respostas OpenAI |
| Mensagens do Anthropic |
| Gemini |
| Gemini |
| 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 |
|---|---|---|
| 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 |
| String | As fases em que a política entra em execução: |
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:
{
"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:
{
"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:
{
"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:
{
"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:
{
"result": "DENY",
"reason": "The message contains a payment card number."
}
campo | Tipo | Descrição |
|---|---|---|
| String | Obrigatório. |
| String | Opcional. Em |
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,ASKnão bloqueia. O resultado é processado como se você tivesse retornadoALLOW. Para bloquear um resultado, retorneDENY. - Em um evento
model_calloumodel_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 |
|---|---|
| Permite a interação. |
| Recusa a interação e retorna o seu |
| Em um |
| Nega a interação. |
O corpo não é um JSON válido ou tem um membro | 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
DENYde 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:
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.