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`

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	Le nom à trois niveaux du service administré dans Unity Catalog, par exemple `main.default.github_mcp`. 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.

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	Le nom à trois niveaux du service administré dans Unity Catalog, par exemple `main.default.github_mcp`. 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.

L'événement contient uniquement du contenu. Il n'inclut pas l'identité de l'utilisateur, de l'agent ou de l'application qui a effectué l'appel.

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

Le corps d’une requête de modèle comprend les messages de la requête, tels que l’invite système et les tours de conversation précédents. Si le client définit une fenêtre de conversation pour la stratégie, le corps ne peut contenir que les messages les plus récents ; ne présumez donc pas que la conversation entière est présente.

Types d’API

Les événements de modèle contiennent les corps de requête et de réponse au format API utilisé par l’appelant. Databricks ne les convertit pas dans un format commun. Le champ api_type indique le format :

`api_type`	Format
`mlflow/v1/chat/completions`	Complétions de chat Databricks, compatibles avec les complétions de chat OpenAI
`mlflow/v1/completions`	Complétions Databricks
`mlflow/v1/embeddings`	Embeddings Databricks
`mlflow/v1/responses`	Réponses ouvertes Databricks
`openai/v1/chat/completions`	Achèvements de discussion OpenAI
`openai/v1/completions`	Achèvements 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
`codex/v1/responses`	Réponses Codex
`typesafe/v1/systemone`	Système un

`api_type`	Format
`mlflow/v1/chat/completions`	Complétions de chat Databricks, compatibles avec les complétions de chat OpenAI
`mlflow/v1/completions`	Complétions Databricks
`mlflow/v1/embeddings`	Embeddings Databricks
`mlflow/v1/responses`	Réponses ouvertes Databricks
`openai/v1/chat/completions`	Achèvements de discussion OpenAI
`openai/v1/completions`	Achèvements 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
`codex/v1/responses`	Réponses Codex
`typesafe/v1/systemone`	Système un

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

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

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

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

Les politiques de service externe échouent par défaut. Databricks refuse l’interaction chaque fois qu’il ne peut pas lire un verdict de 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 pour autoriser le trafic en cas d’échec de l’endpoint.

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 répond, ou les deux. Une politique qui s’exécute sur les deux phases envoie deux requêtes pour chaque interaction.
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.

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", "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.

Comment ça marche​

Conditions requises pour Endpoint​

Demande​

L’objet event​

Types d'événement​

Types d’API​

L’objet config​

Exemples de requête​

Réponse​

Suspendre un appel d’outil pour approbation​

Comment Databricks gère chaque réponse​

Lorsque Databricks appelle l’endpoint​

Traitement des données​

Tester votre endpoint​

Étapes suivantes​