外部サービスポリシー API リファレンス
ベータ版
この機能はベータ版です。ワークスペース管理者は、 Unity Gateway サービス ポリシー プレビューにオプトインすることで、 プレビュー ページからこの機能へのアクセスを制御できます。ワークスペースレベルのプレビューの管理を参照してください。
顧客が 外部サービスポリシー をサービスに関連付けると、Unity Gateway は管理対象の各対話でガードレールベンダーの HTTP Endpoint を呼び出し、Endpoint が返す判定を適用します。このページでは、エンドポイントが実装するコントラクト、つまり Databricks が送信するリクエスト、Databricks が期待するレスポンス、および Databricks が各レスポンスをどのように処理するかを説明します。
このページを使用して、顧客が外部サービスポリシーで使用できるEndpointを構築するか、ベンダーのEndpointが互換性があるかを確認します。顧客のセットアップについては、外部サービスポリシーでパートナー ガードレールを適用するを参照してください。
仕組み
制御された各インタラクションにおいて、Databricksは JSON 本文を持つ POST 要求をEndpointに送信します。Endpointは内容を検査し、 ALLOW、 DENY、またはMCPツール呼び出しの場合は ASKを返します。 Databricksはその判定を適用します。
1つのEndpointで多数の顧客とポリシーに対応できます。顧客はポリシー構成で目的の動作を選択します。Databricks はリクエストのたびにその構成をEndpointに渡します。
Endpointの要件
Endpointは以下の要件を満たす必要があります。
- 顧客が接続で設定するホストとパスでJSON本文を含む
POSTリクエストを受け入れます。 - OAuthマシン間 (M2M) 認証を受け入れます。顧客は、接続時にクライアント ID、クライアント シークレット、トークン Endpoint、およびオプションのスコープを構成します。DatabricksはトークンEndpointからアクセストークンを取得し、リクエストごとに
Authorizationヘッダーで送信します。トークンEndpointは、OAuth 2.0仕様で定義された形式でトークンを返す必要があります。外部サービスは OAuth 2.0 仕様に準拠している必要がありますを参照してください。 - HTTPS を使用してください。Databricks は平文の HTTP 経由で Endpoint を呼び出しません。
- 5秒以内に応答してください。Endpointが時間内に応答しない場合、Databricks は対話を拒否します。
- すべての決定 (ブロックを含む) について、最大 64 KB の応答本文で JSON 判定と共に HTTP
200を返します。
Endpointが異なる検出プロファイルのような複数の動作をサポートしている場合は、ポリシー設定として何を入力するかを顧客に伝えます。
リクエスト
Databricksは、各評価をHTTPリクエストとして接続のホストとパスに送信します。パスは、接続に何もない場合に/になります。
POST /<path> HTTP/1.1
Host: <host>
Authorization: Bearer <access-token>
Content-Type: application/json
本文は、次の2つのメンバーを持つJSONオブジェクトです。
{
"event": {},
"config": {}
}
eventは評価中の相互作用です。eventオブジェクトを参照してください。config顧客のポリシー設定を含むポリシーのオプションを保持します。configオブジェクトを参照してください。
eventオブジェクト
フィールド | 型 | 説明 |
|---|---|---|
| String | インタラクションとフェーズ: |
| String | Unity Catalog内の管理されたサービスの3レベルの名前。例： |
| オブジェクト | 評価対象のコンテンツ。その形状は |
| オブジェクト | 元となるリクエスト。リクエストのコンテキストで結果を判断できます。 |
| String |
|
| String | ガバナンスされたリクエストのOpenTelemetryトレース ID。これを使用して、Logs内の評価をリクエストと照合します。リクエストにトレースがある場合にのみ存在するため、必須ではありません。 |
イベントはコンテンツのみを運びます。呼び出しを行ったユーザー、エージェント、またはアプリのIDは含まれません。
イベントタイプ
| サービスとフェーズ |
|
|
|---|---|---|---|
| MCP サービス、ツールの実行前 |
| プレゼンテーションなし |
| MCPサービス、ツールラン後 | ツールの結果 |
|
| モデルが呼び出される前のモデル サービスまたはモデル プロバイダー サービス | という名前の形式による完全なモデル要求本文。 | プレゼンテーションなし |
| モデル サービスまたはモデル プロバイダー サービス、モデルが応答した後 | 完全なモデル レスポンス本文（名前で指定された形式で） | 完全なモデル要求本文 |
モデルの要求本文には、システム プロンプトや会話の以前のターンなど、要求内のメッセージが含まれています。顧客がポリシーの会話ウィンドウを設定した場合、本文には最新のメッセージのみが含まれる可能性があるため、完全な会話が存在しているとは想定しないでください。
APIタイプ
モデル イベントは、呼び出し元が使用した API 形式でリクエストとレスポンス本体を運びます。Databricks はそれらを共通の形式に変換しません。api_type フィールドは形式の名前を指定します：
| フォーマット |
|---|---|
| OpenAI Chat Completions と互換性のある Databricks Chat Completions |
| Databricks 補完 |
| Databricks 埋め込み |
| Databricks Open Responses |
| OpenAIチャット完了 |
| OpenAI完了 |
| OpenAI Embeddings |
| OpenAI Responses |
| Anthropic Messages |
| Gemini |
| Gemini |
| カーソルチャット完了 |
| Codexの応答 |
|
Unity Gatewayは、より多くのAPIをサポートするにつれてAPIタイプを追加できます。認識できない api_type は解析できないコンテンツとして扱い、DENY のような意図的な評価を返します。
configオブジェクト
config ポリシーのオプションを文字列として保持します。接続またはパスは含まれていません。
フィールド | 型 | 説明 |
|---|---|---|
| String | 顧客が入力した通りのポリシー構成（文字列として渡される JSON オブジェクト）。たとえば |
| String | ポリシーがランされるフェーズ: |
config 他のポリシー オプションを含めることができます。認識できないキーは無視してください。
リクエストの例
MCPツールの呼び出し、ツールラン前:
{
"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"
}
}
MCP ツールのラン後のツールの結果:
{
"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"
}
}
モデルが呼び出される前のモデル要求：
{
"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"
}
}
モデルが応答した後のモデルの応答:
{
"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"
}
}
レスポンス
JSON本文でHTTP 200を返します：
{
"result": "DENY",
"reason": "The message contains a payment card number."
}
フィールド | 型 | 説明 |
|---|---|---|
| String | 必須。 |
| String | オプション。 |
ブロックをHTTP 200 で DENY の判定として返します（HTTPエラーではありません）。DatabricksはHTTPエラーを失敗した評価として扱うため、インタラクションを拒否しますが、呼び出し元には理由は表示されません。
外部サービスポリシーはコンテンツを編集または書き換えることができないため、変更されたペイロードを返さないでください。
ツールの呼び出しを承認保留にする
tool_call イベントで ASK を返し、ユーザーが承認するまでツール呼び出しを保持します。ユーザーが承認すると、Databricksはツール呼び出しをランします。ASK イベントの時のみ tool_call を返します：
tool_resultイベントでは、ASKはブロックしません。結果はALLOWを返したかのように進みます。結果をブロックするには、DENYを返します。model_callまたはmodel_resultイベントが発生したときに、モデルサービスとモデルプロバイダーサービスがユーザーに承認を求めることができないため、Databricksは対話をブロックします。
Databricksが各応答を処理する方法
外部サービスのポリシーはクローズで失敗します。Endpointから判定を読み取ることができない場合、Databricksはやり取りを拒否します：
レスポンス | Databricksの機能 |
|---|---|
| 対話を許可します。 |
| インタラクションを拒否し、あなたの |
|
|
| 対話を拒否します。 |
本文が有効なJSONでないか、最上位レベルの | 対話を拒否します。 |
ボディが64 KBを超えています | 対話を拒否します。 |
HTTP ステータスが 2xx ではありません | 対話を拒否します。 |
5秒以内に応答がありません | 対話を拒否します。 |
接続が失敗しました | 対話を拒否します。 |
顧客は、Endpointの障害時にトラフィックを許可する外部サービスポリシーを構成できません。
DatabricksがEndpointを呼び出すとき
- Databricksは、ポリシーが実行される各フェーズでendpointを1回呼び出します。サービスが呼び出される前、応答した後、またはその両方です。両方のフェーズで実行されるポリシーは、各インタラクションに対して2つのリクエストを送信します。
- 顧客がポリシーを Log モードで添付した場合、Databricks は引き続き Endpoint を呼び出して判定を記録しますが、適用はしません。
- 外部サービスポリシーの前に実行される別のポリシーからの
DENYは、DatabricksがEndpointを呼び出す前にインタラクションを停止できます。評価順序を参照してください。
データ処理
各リクエストには顧客コンテンツが含まれます。モデルのリクエストおよびレスポンスの本文（システムプロンプトや以前のメッセージを含む）、ならびにMCPツールの名前、引数、結果が含まれます。それを顧客データとして扱い、あなたのEndpointが何を、どのくらいの期間、どこで処理するのかを顧客に対して文書化してください。
Endpointのテスト
顧客がEndpointを使用する前に、サンプルリクエストを送信し、5秒以内にALLOW、DENY、またはASKのresultでHTTP 200が返されることを確認します。
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"}}'
完全なフローをテストするには、Endpointを使用する外部サービスポリシーをDatabricksワークスペース内のサービスに Log モードでアタッチし、統合トレーステーブルで記録された判定を確認してください。外部サービスポリシーでのパートナーガードレールの適用を参照してください。