Référence de l’API de politique de service externe
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
POSTrequê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
Authorizationde 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
200avec 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.
POST /<path> HTTP/1.1
Host: <host>
Authorization: Bearer <access-token>
Content-Type: application/json
Le corps est un objet JSON avec deux membres :
{
"event": {},
"config": {}
}
eventest l'interaction en cours d'évaluation. Voir L'objetevent.configcontient les options de la stratégie, y compris la configuration de la stratégie du client. Voir L’objetconfig.
L’objet event
Ignorez les champs event que vous ne reconnaissez pas.
Champ | Type | Description |
|---|---|---|
| Chaîne | L'interaction et la phase : |
| Chaîne | L’identifiant du service régi. Les événements MCP utilisent le nom à trois niveaux dans Unity Catalog, par exemple |
| Objet | Le contenu en cours d’évaluation. Sa forme dépend de |
| 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 |
| Chaîne | Format d’API de |
| 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. |
| 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
| Service et phase |
|
|
|---|---|---|---|
| Service MCP, avant l'exécution de l'outil |
| Non présent |
| Service MCP, après l’exécution de l’outil | Résultat de l’outil |
|
| 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 | Non présent |
| 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 | 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 :
| Format |
|---|---|
| Complétions de chat Databricks, compatibles avec les complétions de chat OpenAI |
| Embeddings Databricks |
| Réponses ouvertes Databricks |
| Achèvements de discussion OpenAI |
| Intégrations OpenAI |
| Réponses OpenAI |
| Messages Anthropic |
| Gemini |
| Gemini |
| 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 |
|---|---|---|
| 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 |
| Chaîne | Les phases auxquelles la politique s’applique : |
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 :
{
"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 :
{
"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é :
{
"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 :
{
"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 :
{
"result": "DENY",
"reason": "The message contains a payment card number."
}
Champ | Type | Description |
|---|---|---|
| Chaîne | Obligatoire. |
| Chaîne | Facultatif. Sur |
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,ASKne bloque pas. Le résultat passe comme si vous aviez renvoyéALLOW. Pour bloquer un résultat, renvoyezDENY. - Lors d'un événement
model_calloumodel_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 |
|---|---|
| Autorise l'interaction. |
| Refuse l'interaction et renvoie |
| Sur un |
| Refuse l'interaction. |
Le corps n'est pas un JSON valide ou il possède un membre | 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
DENYprovenant 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 :
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.