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
campo | Tipo | Descrição |
|---|---|---|
| String | A interação e a fase: |
| String | O nome de três níveis do serviço governado 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. |
O evento carrega apenas conteúdo. Não inclui a identidade do usuário, agente ou aplicativo que fez a chamada.
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 |
O corpo de uma 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, portanto, não assuma que a conversa completa está presente.
Tipos de API
Eventos de modelo carregam os corpos da solicitação e resposta no formato de API usado pelo chamador. 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 |
| Completions do Databricks |
| Embeddings do Databricks |
| Respostas abertas da Databricks |
| Conclusões de chat do OpenAI |
| Conclusões da OpenAI |
| Incorporações OpenAI |
| Respostas OpenAI |
| Mensagens do Anthropic |
| Gemini |
| Gemini |
| Conclusões de bate-papo de cursor |
| Respostas do Codex |
|
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",
"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",
"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": "main.default.support_assistant",
"api_type": "mlflow/v1/chat/completions",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"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": "main.default.support_assistant",
"api_type": "mlflow/v1/chat/completions",
"trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
"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
As políticas de serviço externo falham de forma fechada. 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 para permitir o tráfego quando o endpoint falha.
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 que o serviço seja chamado, depois que ele responde ou ambos. Uma política em execução nas duas fases envia duas solicitações para cada interaçã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.
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", "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.