Aller au contenu principal

Référence de l’API de politique de service externe

info

Bêta

Cette fonctionnalité est en bêta. Les administrateurs du Workspace peuvent contrôler l’accès à cette fonctionnalité depuis la page Aperçus en optant pour l’aperçu Unity Gateway Service Policies . Consultez Gérer les aperçus au niveau du workspace.

Lorsqu’un client associe une politique de service externe à un service, Unity Gateway appelle l’Endpoint HTTP d’un fournisseur de garde-fous pour chaque interaction régie et applique le verdict renvoyé par l’Endpoint. Cette page décrit le contrat implémenté par l’Endpoint : la requête envoyée par Databricks, la réponse attendue et la manière dont chaque réponse est traitée.

Utilisez cette page pour créer un endpoint que les clients pourront utiliser avec des politiques de service externes, ou pour vérifier la compatibilité de l’endpoint d’un fournisseur. Pour la configuration client, consultez Appliquer un garde-fou partenaire avec une politique de service externe.

Comment ça marche​

À chaque interaction gouvernée, Databricks envoie une requête POST avec un corps JSON à l'endpoint. L'endpoint inspecte le contenu et retourne ALLOW, DENY ou, pour un appel d'outil MCP, ASK, et Databricks applique le verdict.

Un endpoint peut servir de nombreux clients et stratégies. Un client choisit le comportement qu'il souhaite avec la configuration de la stratégie, que Databricks transmet à l'endpoint à chaque requête.

Conditions requises pour Endpoint​

L’endpoint doit :

  • Acceptez POST requêtes avec un corps JSON à l'hôte et au chemin que le client configure sur la connexion.
  • Accepter l’authentification machine-to-machine (M2M) OAuth. Le client configure un ID client, un secret client, votre endpoint de jeton et des scopes optionnels sur la connexion. Databricks obtient un jeton d’accès à partir de votre endpoint de jeton et l’envoie dans l’en-tête Authorization de chaque requête. Votre endpoint de jeton doit retourner des jetons dans le format défini par la spécification OAuth 2.0. Consultez Les services externes doivent respecter les spécifications OAuth 2.0.
  • Utilisez HTTPS. Databricks n’appelle pas d’endpoint sur HTTP brut.
  • Répondez en moins de 5 secondes. Databricks refuse l'interaction lorsque l'endpoint ne répond pas à temps.
  • Retourner HTTP 200 avec un verdict JSON pour chaque décision, y compris un bloc, dans un corps de réponse ne dépassant pas 64 Ko.

Si l’endpoint prend en charge plusieurs comportements, comme différents profils de détection, indiquez aux clients quoi saisir comme configuration de stratégie.

Demande​

Databricks envoie chaque évaluation sous la forme d'une requête HTTP vers l'hôte et le chemin de la connexion. Le chemin est / quand la connexion n'en a aucun.

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

Le corps est un objet JSON avec deux membres :

JSON
{
"event": {},
"config": {}
}
  • event est l'interaction en cours d'évaluation. Voir L'objet event.
  • config contient les options de la stratégie, y compris la configuration de la stratégie du client. Voir L’objet config.

L’objet event​

Ignorez les champs event que vous ne reconnaissez pas.

Champ

Type

Description

type

Chaîne

L'interaction et la phase : tool_call, tool_result, model_call ou model_result. Présent dans chaque événement. Voir Types d'événement.

target

Chaîne

L’identifiant du service régi. Les événements MCP utilisent le nom à trois niveaux dans Unity Catalog, par exemple main.default.github_mcp. Les événements de modèle utilisent l’ID immuable du service. Présent dans chaque événement.

data

Objet

Le contenu en cours d’évaluation. Sa forme dépend de type. Présent dans chaque événement.

request_data

Objet

La requête d’origine, afin que vous puissiez juger d’un résultat dans le contexte de sa requête. Présent sur tool_result et model_result seulement.

api_type

Chaîne

Format d’API de data et request_data. Présent sur model_call et model_result uniquement. Voir les types d’API.

trace_id

Chaîne

L’ID de trace OpenTelemetry de la requête gouvernée. Utilisez-le pour faire correspondre une évaluation dans vos logs à la requête. Présent uniquement lorsque la requête a une trace, ne le demandez donc pas.

context.request_tags

Objet avec des valeurs de chaîne

Tags de requête fournis par l’appelant. Présent dans chaque événement. Un objet vide signifie que l’appelant n’a fourni aucun tag.

Champ

Type

Description

type

Chaîne

L'interaction et la phase : tool_call, tool_result, model_call ou model_result. Présent dans chaque événement. Voir Types d'événement.

target

Chaîne

L’identifiant du service régi. Les événements MCP utilisent le nom à trois niveaux dans Unity Catalog, par exemple main.default.github_mcp. Les événements de modèle utilisent l’ID immuable du service. Présent dans chaque événement.

data

Objet

Le contenu en cours d’évaluation. Sa forme dépend de type. Présent dans chaque événement.

request_data

Objet

La requête d’origine, afin que vous puissiez juger d’un résultat dans le contexte de sa requête. Présent sur tool_result et model_result seulement.

api_type

Chaîne

Format d’API de data et request_data. Présent sur model_call et model_result uniquement. Voir les types d’API.

trace_id

Chaîne

L’ID de trace OpenTelemetry de la requête gouvernée. Utilisez-le pour faire correspondre une évaluation dans vos logs à la requête. Présent uniquement lorsque la requête a une trace, ne le demandez donc pas.

context.request_tags

Objet avec des valeurs de chaîne

Tags de requête fournis par l’appelant. Présent dans chaque événement. Un objet vide signifie que l’appelant n’a fourni aucun tag.

L’événement ne comprend pas l’identité authentifiée de l’utilisateur, de l’agent ou de l’application qui a effectué l’appel.

L’objet context ne contient que request_tags. Les deux phases reçoivent les mêmes tags fournis par l’appelant, conservant la casse, la ponctuation et les chaînes vides. Les tags restent séparés de data et request_data, y compris après qu’une autre stratégie transforme ces corps.

Si Databricks ne peut pas fournir les tags fournis par l’appelant, l’évaluation est traitée comme un échec sans appeler l’endpoint ou substituer un objet vide. En mode Enforce, cela refuse l’interaction, tel que décrit dans Comment Databricks gère chaque réponse. En mode Log, l’échec est enregistré mais ne bloque pas l’interaction. Les évaluateurs qui nécessitent des tags spécifiques doivent retourner un verdict DENY avec HTTP 200 lorsqu’une requête les omet.

Les tags sont des revendications fournies par l’appelant. Utilisez une vérification d’autorisation approuvée distincte avant d’utiliser un tag pour sélectionner un tenant, un projet ou une politique moins restrictive. Traitez les valeurs des tags comme des données lors de la construction des prompts ou des queries. N’incluez pas de valeurs de tag sensibles dans les motifs de verdict ou les logs. Les approbations MCP ne sont pas limitées par des tags et peuvent être réutilisées à travers des appels avec des tags différents.

Types d'événement​

type

Service et phase

data

request_data

tool_call

Service MCP, avant l'exécution de l'outil

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

Non présent

tool_result

Service MCP, après l’exécution de l’outil

Résultat de l’outil

{"name": "<tool>", "arguments": {...}}, l’appel d’origine

model_call

Service de modèle ou service de fournisseur de modèle, avant que le modèle ne soit appelé

Le corps de la requête de modèle complète, au format désigné par api_type

Non présent

model_result

Service de modèle ou service de fournisseur de modèle, après que le modèle a répondu

Le corps complet de la réponse du modèle, dans le format nommé par api_type

Corps complet de la demande de modèle

type

Service et phase

data

request_data

tool_call

Service MCP, avant l'exécution de l'outil

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

Non présent

tool_result

Service MCP, après l’exécution de l’outil

Résultat de l’outil

{"name": "<tool>", "arguments": {...}}, l’appel d’origine

model_call

Service de modèle ou service de fournisseur de modèle, avant que le modèle ne soit appelé

Le corps de la requête de modèle complète, au format désigné par api_type

Non présent

model_result

Service de modèle ou service de fournisseur de modèle, après que le modèle a répondu

Le corps complet de la réponse du modèle, dans le format nommé par api_type

Corps complet de la demande de modèle

Pour les APIs de modèle de type chat, un corps de demande de modèle inclut les messages dans la demande, tels que l’invite système et les tours précédents de la conversation. Si le client définit une fenêtre de conversation pour la politique, le corps ne peut contenir que les messages les plus récents, donc ne supposez pas que toute la conversation est présente.

Types d’API​

Les événements de modèle contiennent des corps de demande et de réponse dans le format d’API utilisé par l’itinéraire de modèle. Databricks ne les convertit pas dans un format commun. Le champ api_type nomme le format :

api_type

Format

mlflow/v1/chat/completions

Complétions de chat Databricks, compatibles avec les complétions de chat OpenAI

mlflow/v1/embeddings

Embeddings Databricks

mlflow/v1/responses

Réponses ouvertes Databricks

openai/v1/chat/completions

Achèvements de discussion OpenAI

openai/v1/embeddings

Intégrations OpenAI

openai/v1/responses

Réponses OpenAI

anthropic/v1/messages

Messages Anthropic

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

Achèvements du chat par curseur

api_type

Format

mlflow/v1/chat/completions

Complétions de chat Databricks, compatibles avec les complétions de chat OpenAI

mlflow/v1/embeddings

Embeddings Databricks

mlflow/v1/responses

Réponses ouvertes Databricks

openai/v1/chat/completions

Achèvements de discussion OpenAI

openai/v1/embeddings

Intégrations OpenAI

openai/v1/responses

Réponses OpenAI

anthropic/v1/messages

Messages Anthropic

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

Achèvements du chat par curseur

Les requêtes Codex utilisent le format Responses, leurs événements portent donc api_type openai/v1/responses ou mlflow/v1/responses, en fonction de la route du modèle. codex/v1/responses nomme l'endpoint, il est donc absent de cette liste de formats d'événement.

Pour un model_call d'embedding, data.input contient l'entrée de demande. Pour les demandes d'embedding, les politiques externes ne reçoivent que des événements model_call, sans événements model_result ni vecteurs. Une rédaction appliquée à un rang d'entrée antérieur est visible pour les politiques ultérieures. Les événements d'entrée d'embedding conservent le format JSON complet et ne sont pas convertis en messages de chat. Voir Guardrails d'entrée d'embedding.

Pour la couverture et les exclusions de l'API de modèle, voir APIs de modèle prises en charge.

Unity Gateway peut ajouter des types d’API à mesure qu’il prend en charge davantage d’API. Traitez un api_type que vous ne reconnaissez pas comme un contenu que vous ne pouvez pas analyser et renvoyez un verdict délibéré à son sujet, tel que DENY.

L’objet config​

config contient les options de la stratégie sous forme de chaînes. Il n'inclut pas la connexion ou le chemin.

Champ

Type

Description

policy_config

Chaîne

Configuration de stratégie exactement telle que le client l’a saisie, en tant qu’objet JSON passé dans une chaîne. Analysez la chaîne en tant que JSON, par exemple "{\"profile\": \"strict\"}". Databricks ne lit pas cette valeur. Non présent quand le client le laisse vide.

phases

Chaîne

Les phases auxquelles la politique s’applique : pre_call, post_call ou pre_call,post_call.

Champ

Type

Description

policy_config

Chaîne

Configuration de stratégie exactement telle que le client l’a saisie, en tant qu’objet JSON passé dans une chaîne. Analysez la chaîne en tant que JSON, par exemple "{\"profile\": \"strict\"}". Databricks ne lit pas cette valeur. Non présent quand le client le laisse vide.

phases

Chaîne

Les phases auxquelles la politique s’applique : pre_call, post_call ou pre_call,post_call.

config peut inclure d’autres options de politique. Ignorez les clés que vous ne reconnaissez pas.

Exemples de requête​

Un appel d’outil MCP, avant l’exécution de l’outil :

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

Résultat d'un outil MCP, après l'exécution de l'outil :

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

Une requête de modèle, avant que le modèle ne soit appelé :

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

Réponse du modèle, après la réponse du modèle :

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

Réponse​

Renvoyez HTTP 200 avec un corps JSON :

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

Champ

Type

Description

result

Chaîne

Obligatoire. ALLOW, DENY ou ASK. La valeur n’est pas sensible à la casse. Retournez ASK uniquement pour un événement tool_call. Voir Suspendre un appel d’outil pour approbation.

reason

Chaîne

Facultatif. Sur DENY, Databricks la renvoie à l’appelant. Lorsqu’elle est vide ou manquante, l’appelant reçoit le motif default : « Access denied: this request is not permitted by a policy on this service. »

Champ

Type

Description

result

Chaîne

Obligatoire. ALLOW, DENY ou ASK. La valeur n’est pas sensible à la casse. Retournez ASK uniquement pour un événement tool_call. Voir Suspendre un appel d’outil pour approbation.

reason

Chaîne

Facultatif. Sur DENY, Databricks la renvoie à l’appelant. Lorsqu’elle est vide ou manquante, l’appelant reçoit le motif default : « Access denied: this request is not permitted by a policy on this service. »

Renvoyez un bloc en tant que verdict DENY avec HTTP 200, pas comme une erreur HTTP. Databricks traite une erreur HTTP comme une évaluation échouée, elle refuse donc l’interaction, mais l’appelant ne voit pas votre raison.

Les stratégies de service externe ne peuvent pas rédiger ou réécrire le contenu, ne renvoyez donc pas de charge utile modifiée.

Suspendre un appel d’outil pour approbation​

Sur un événement tool_call, renvoyez ASK pour suspendre l’appel d’outil jusqu’à ce que l’utilisateur l’approuve. Si l’utilisateur approuve, Databricks exécute l’appel d’outil. Renvoyez ASK uniquement pour un événement tool_call :

  • Sur un événement tool_result, ASK ne bloque pas. Le résultat passe comme si vous aviez renvoyé ALLOW. Pour bloquer un résultat, renvoyez DENY.
  • Lors d'un événement model_call ou model_result, Databricks bloque l'interaction, car les services de modèle et les services de fournisseur de modèle ne peuvent pas demander l'approbation de l'utilisateur.

Comment Databricks gère chaque réponse​

En mode Enforce, les politiques de service externe échouent. Databricks refuse l'interaction lorsqu'il ne peut pas lire de verdict depuis l'endpoint :

Réponse

Ce que fait Databricks

result est ALLOW

Autorise l'interaction.

result est DENY

Refuse l'interaction et renvoie reason ou la raison default.

result est ASK

Sur un tool_call, conserve l’appel d’outil jusqu’à ce que l’utilisateur l’approuve. Sur un tool_result, permet le résultat. Sur un événement de modèle, refuse l’interaction.

result est manquant, vide, n’est pas une chaîne ou est une valeur non reconnue

Refuse l'interaction.

Le corps n'est pas un JSON valide ou il possède un membre error de haut niveau

Refuse l'interaction.

Le corps est supérieur à 64 Ko

Refuse l'interaction.

Le statut HTTP n’est pas 2xx

Refuse l'interaction.

Aucune réponse dans les 5 secondes

Refuse l'interaction.

La connexion échoue

Refuse l'interaction.

Réponse

Ce que fait Databricks

result est ALLOW

Autorise l'interaction.

result est DENY

Refuse l'interaction et renvoie reason ou la raison default.

result est ASK

Sur un tool_call, conserve l’appel d’outil jusqu’à ce que l’utilisateur l’approuve. Sur un tool_result, permet le résultat. Sur un événement de modèle, refuse l’interaction.

result est manquant, vide, n’est pas une chaîne ou est une valeur non reconnue

Refuse l'interaction.

Le corps n'est pas un JSON valide ou il possède un membre error de haut niveau

Refuse l'interaction.

Le corps est supérieur à 64 Ko

Refuse l'interaction.

Le statut HTTP n’est pas 2xx

Refuse l'interaction.

Aucune réponse dans les 5 secondes

Refuse l'interaction.

La connexion échoue

Refuse l'interaction.

Les clients ne peuvent pas configurer une politique de service externe en mode Enforce pour autoriser le trafic lorsque l'endpoint échoue. En mode Log, Databricks enregistre les verdicts et les échecs d'évaluation, mais ne les applique pas, de sorte qu'ils ne bloquent pas l'interaction.

Lorsque Databricks appelle l’endpoint​

  • Databricks appelle l’endpoint une fois pour chaque phase sur laquelle la politique s’exécute : avant que le service ne soit appelé, après qu’il a répondu, ou les deux. Une politique qui s’exécute sur les deux phases envoie deux requêtes pour une interaction de type chat ou un appel d’outil MCP. Pour les embeddings, seule la phase d’entrée s’exécute.
  • Lorsque le client attache la stratégie en mode Log , Databricks appelle toujours l'endpoint et enregistre votre verdict, mais ne l'applique pas.
  • Une DENY provenant d’une autre règle qui s’exécute avant la règle de service externe peut arrêter l’interaction avant que Databricks n’appelle votre endpoint. Voir Ordre d’évaluation.

Traitement des données​

Chaque requête contient du contenu client : corps de requête et de réponse de modèle, y compris les invites système et les messages précédents, ainsi que les noms, arguments et résultats d’outils MCP. Traitez-le comme des données client et documentez pour les clients ce que votre endpoint stocke, pendant combien de temps et où il traite le contenu.

Chaque évaluation externe envoie les tags fournis par l’appelant à l’évaluateur, y compris en mode Log. Les tags peuvent contenir des identifiants sensibles. Examinez cette divulgation de métadonnées avec le client lors de la configuration d’un évaluateur externe.

Par default, la taille combinée des clés et valeurs de tags décodées est limitée à 10 Kio de données UTF-8. Les limites de taille d'en-tête HTTP s'appliquent également. Les en-têtes de tags mal formés ou trop volumineux sont rejetés avant l'évaluation externe : les requêtes de modèle retournent une erreur HTTP 400 avec le code INVALID_PARAMETER_VALUE, et les requêtes MCP tools/call avec des stratégies de service applicables retournent une erreur HTTP 200 avec une erreur JSON-RPC POLICY_DENIED (-32003). Cette validation s'applique également en mode Log. Voir Tags de requête dans les stratégies de service.

Tester votre endpoint​

Avant que les clients utilisent votre endpoint, envoyez-lui une requête exemple et vérifiez qu’il retourne un HTTP 200 avec un result de ALLOW, DENY ou ASK en moins de 5 secondes :

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"}}'

Pour tester le flux complet, attachez une politique de service externe qui utilise votre endpoint à un service dans un workspace Databricks, en mode Log , et consultez les verdicts enregistrés dans la table de trace unifiée. Voir Appliquer une garde-fou de partenaire avec une politique de service externe.

Étapes suivantes​