メインコンテンツまでスキップ

外部サービスポリシー 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リクエストとして接続のホストとパスに送信します。パスは、接続に何もない場合に/になります。

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

本文は、次の2つのメンバーを持つJSONオブジェクトです。

JSON
{
"event": {},
"config": {}
}
  • event は評価中の相互作用です。event オブジェクトを参照してください。
  • config 顧客のポリシー設定を含むポリシーのオプションを保持します。config オブジェクトを参照してください。

eventオブジェクト​

認識できない event フィールドは無視されます。

フィールド

型

説明

type

String

インタラクションとフェーズ: tool_call、 tool_result、 model_call、または model_result。すべてのイベントに存在します。イベントタイプを参照してください。

target

String

管理対象サービスの識別子です。MCP イベントは、Unity Catalog の 3 レベル名(例: main.default.github_mcp)を使用します。モデル イベントは、サービスの不変 ID を使用します。すべてのイベントに存在します。

data

オブジェクト

評価対象のコンテンツ。その形状は type に依存します。すべてのイベントに存在します。

request_data

オブジェクト

元となるリクエスト。リクエストのコンテキストで結果を判断できます。tool_result および model_result のみに存在します。

api_type

String

data と request_data の API 形式。model_call と model_result にのみ存在します。APIタイプを参照してください。

trace_id

String

ガバナンスされたリクエストのOpenTelemetryトレース ID。これを使用して、Logs内の評価をリクエストと照合します。リクエストにトレースがある場合にのみ存在するため、必須ではありません。

context.request_tags

文字列値を持つオブジェクト

呼び出し元が提供したリクエストタグ。すべてのイベントに存在します。空のオブジェクトは、呼び出し元がタグを提供しなかったことを意味します。

フィールド

型

説明

type

String

インタラクションとフェーズ: tool_call、 tool_result、 model_call、または model_result。すべてのイベントに存在します。イベントタイプを参照してください。

target

String

管理対象サービスの識別子です。MCP イベントは、Unity Catalog の 3 レベル名(例: main.default.github_mcp)を使用します。モデル イベントは、サービスの不変 ID を使用します。すべてのイベントに存在します。

data

オブジェクト

評価対象のコンテンツ。その形状は type に依存します。すべてのイベントに存在します。

request_data

オブジェクト

元となるリクエスト。リクエストのコンテキストで結果を判断できます。tool_result および model_result のみに存在します。

api_type

String

data と request_data の API 形式。model_call と model_result にのみ存在します。APIタイプを参照してください。

trace_id

String

ガバナンスされたリクエストのOpenTelemetryトレース ID。これを使用して、Logs内の評価をリクエストと照合します。リクエストにトレースがある場合にのみ存在するため、必須ではありません。

context.request_tags

文字列値を持つオブジェクト

呼び出し元が提供したリクエストタグ。すべてのイベントに存在します。空のオブジェクトは、呼び出し元がタグを提供しなかったことを意味します。

このイベントには、呼び出しを行ったユーザー、エージェント、またはアプリの認証済みIDは含まれません。

context オブジェクトには request_tags のみが含まれます。両方のフェーズは、呼び出し元が提供した同じタグを受け取り、大文字と小文字、句読点、空の文字列を保持します。タグは data および request_data とは別のまま保持され、別のポリシーがこれらの本体を変換した後も保持されます。

Databricks が呼び出し元から提供されたタグを提供できない場合、Endpoint を呼び出したり空のオブジェクトを代入したりすることなく、評価を失敗として扱います。Databricks が呼び出し元から提供されたタグを提供できない場合、エンドポイントを呼び出したり空のオブジェクトを代入したりすることなく、評価を失敗として扱います。Log モードでは、失敗は記録されますが、対話はブロックされません。特定のタグを必要とする評価者は、リクエストでタグが省略された場合に HTTP 200 で DENY の判定を返さなければなりません。

タグは呼び出し元が提供するクレームです。タグを使用してテナント、プロジェクト、または制限の少ないポリシーを選択する前に、個別の信頼できる認可チェックを使用します。プロンプトやクエリーを構築する際には、タグ値をデータとして扱います。判定理由や Logs に機密性の高いタグ値を含めないでください。MCP の承認はタグに限定されるものではなく、異なるタグを持つ呼び出し間で再利用できます。

イベントタイプ​

type

サービスとフェーズ

data

request_data

tool_call

MCP サービス、ツールの実行前

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

プレゼンテーションなし

tool_result

MCPサービス、ツールラン後

ツールの結果

{"name": "<tool>", "arguments": {...}}、発信元の呼び出し

model_call

モデルが呼び出される前のモデル サービスまたはモデル プロバイダー サービス

という名前の形式による完全なモデル要求本文。 api_type

プレゼンテーションなし

model_result

モデル サービスまたはモデル プロバイダー サービス、モデルが応答した後

完全なモデル レスポンス本文(名前で指定された形式で) api_type

完全なモデル要求本文

type

サービスとフェーズ

data

request_data

tool_call

MCP サービス、ツールの実行前

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

プレゼンテーションなし

tool_result

MCPサービス、ツールラン後

ツールの結果

{"name": "<tool>", "arguments": {...}}、発信元の呼び出し

model_call

モデルが呼び出される前のモデル サービスまたはモデル プロバイダー サービス

という名前の形式による完全なモデル要求本文。 api_type

プレゼンテーションなし

model_result

モデル サービスまたはモデル プロバイダー サービス、モデルが応答した後

完全なモデル レスポンス本文(名前で指定された形式で) api_type

完全なモデル要求本文

チャット形式のモデル APIs の場合、モデルリクエストの本文には、システムプロンプトや会話の以前のターンなど、リクエスト内のメッセージが含まれます。顧客がポリシーに会話ウィンドウを設定すると、本文には直近のメッセージのみが含まれる場合があります。そのため、会話全体が含まれているとは限りません。

APIタイプ​

モデルイベントは、モデルルートで使用される API 形式でリクエスト本文とレスポンス本文を運搬します。Databricksは、それらを共通の形式に変換しません。api_type フィールドは形式に名前を付けます。

api_type

フォーマット

mlflow/v1/chat/completions

OpenAI Chat Completions と互換性のある Databricks Chat Completions

mlflow/v1/embeddings

Databricks 埋め込み

mlflow/v1/responses

Databricks Open Responses

openai/v1/chat/completions

OpenAIチャット完了

openai/v1/embeddings

OpenAI Embeddings

openai/v1/responses

OpenAI Responses

anthropic/v1/messages

Anthropic Messages

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

カーソルチャット完了

api_type

フォーマット

mlflow/v1/chat/completions

OpenAI Chat Completions と互換性のある Databricks Chat Completions

mlflow/v1/embeddings

Databricks 埋め込み

mlflow/v1/responses

Databricks Open Responses

openai/v1/chat/completions

OpenAIチャット完了

openai/v1/embeddings

OpenAI Embeddings

openai/v1/responses

OpenAI Responses

anthropic/v1/messages

Anthropic Messages

gemini/v1/generateContent

Gemini generateContent

gemini/v1/streamGenerateContent

Gemini streamGenerateContent

cursor/v1/chat/completions

カーソルチャット完了

Codexの要求はResponses形式を使用するため、モデルのルートに応じてイベントに api_type openai/v1/responses または mlflow/v1/responses が含まれます。codex/v1/responses はendpointに名前を付けるため、このイベント形式リストには含まれていません。

埋め込み model_call の場合、 data.input には要求入力が含まれます。埋め込み要求の場合、外部ポリシーは model_call イベントのみを受信し、 model_result イベントまたはベクトルは受信しません。初期入力ランクで強制された redaction は、以降のポリシーで表示されます。埋め込み入力イベントは完全な JSON 形式を保持し、チャットメッセージに変換されません。埋め込み入力ガードレールを参照してください。

モデル API のカバレッジおよび除外の詳細については、「サポートされているモデル API」を参照してください。

Unity Gatewayは、より多くのAPIをサポートするにつれてAPIタイプを追加できます。認識できない api_type は解析できないコンテンツとして扱い、DENY のような意図的な評価を返します。

configオブジェクト​

config ポリシーのオプションを文字列として保持します。接続またはパスは含まれていません。

フィールド

型

説明

policy_config

String

顧客が入力した通りのポリシー構成(文字列として渡される JSON オブジェクト)。たとえば "{\"profile\": \"strict\"}" のように、文字列を JSON として解析します。Databricks はこの値を読み取りません。顧客が空のままにすると、存在しません。

phases

String

ポリシーがランされるフェーズ: pre_call、post_call、または pre_call,post_call。

フィールド

型

説明

policy_config

String

顧客が入力した通りのポリシー構成(文字列として渡される JSON オブジェクト)。たとえば "{\"profile\": \"strict\"}" のように、文字列を JSON として解析します。Databricks はこの値を読み取りません。顧客が空のままにすると、存在しません。

phases

String

ポリシーがランされるフェーズ: pre_call、post_call、または pre_call,post_call。

config 他のポリシー オプションを含めることができます。認識できないキーは無視してください。

リクエストの例​

MCPツールの呼び出し、ツールラン前:

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

MCP ツールのラン後のツールの結果:

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

モデルが呼び出される前のモデル要求:

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

モデルが応答した後のモデルの応答:

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

レスポンス​

JSON本文でHTTP 200を返します:

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

フィールド

型

説明

result

String

必須。ALLOW、DENY、またはASK。値は大文字と小文字を区別しません。tool_callイベントの場合のみASKを返します。承認のためにツール呼び出しを保留するを参照してください。

reason

String

オプション。DENY の場合、Databricks はそれを呼び出し元に返します。空であるか欠落している場合、呼び出し元はdefaultの理由「Access denied: this request is not permitted by a policy on this サービス.」を受け取ります。

フィールド

型

説明

result

String

必須。ALLOW、DENY、またはASK。値は大文字と小文字を区別しません。tool_callイベントの場合のみASKを返します。承認のためにツール呼び出しを保留するを参照してください。

reason

String

オプション。DENY の場合、Databricks はそれを呼び出し元に返します。空であるか欠落している場合、呼び出し元はdefaultの理由「Access denied: this request is not permitted by a policy on this サービス.」を受け取ります。

ブロックをHTTP 200 で DENY の判定として返します(HTTPエラーではありません)。DatabricksはHTTPエラーを失敗した評価として扱うため、インタラクションを拒否しますが、呼び出し元には理由は表示されません。

外部サービスポリシーはコンテンツを編集または書き換えることができないため、変更されたペイロードを返さないでください。

ツールの呼び出しを承認保留にする​

tool_call イベントで ASK を返し、ユーザーが承認するまでツール呼び出しを保持します。ユーザーが承認すると、Databricksはツール呼び出しをランします。ASK イベントの時のみ tool_call を返します:

  • tool_result イベントでは、ASK はブロックしません。結果は ALLOW を返したかのように進みます。結果をブロックするには、DENY を返します。
  • model_callまたはmodel_resultイベントが発生したときに、モデルサービスとモデルプロバイダーサービスがユーザーに承認を求めることができないため、Databricksは対話をブロックします。

Databricksが各応答を処理する方法​

強制モードでは、外部サービスポリシーはクローズドに失敗します。Databricksは、Endpointから判定を読み取ることができない場合、対話を拒否します:

レスポンス

Databricksの機能

result は ALLOW

対話を許可します。

result は DENY

インタラクションを拒否し、あなたの reason、または default の理由を返します。

result は ASK

tool_callでは、ユーザーが承認するまでツール呼び出しを保持します。tool_resultでは、結果を許可します。モデル イベントでは、対話を拒否します。

result が欠落しているか、空であるか、文字列ではないか、認識できない値です

対話を拒否します。

本文が有効なJSONでないか、最上位レベルのerrorメンバーがあります

対話を拒否します。

ボディが64 KBを超えています

対話を拒否します。

HTTP ステータスが 2xx ではありません

対話を拒否します。

5秒以内に応答がありません

対話を拒否します。

接続が失敗しました

対話を拒否します。

レスポンス

Databricksの機能

result は ALLOW

対話を許可します。

result は DENY

インタラクションを拒否し、あなたの reason、または default の理由を返します。

result は ASK

tool_callでは、ユーザーが承認するまでツール呼び出しを保持します。tool_resultでは、結果を許可します。モデル イベントでは、対話を拒否します。

result が欠落しているか、空であるか、文字列ではないか、認識できない値です

対話を拒否します。

本文が有効なJSONでないか、最上位レベルのerrorメンバーがあります

対話を拒否します。

ボディが64 KBを超えています

対話を拒否します。

HTTP ステータスが 2xx ではありません

対話を拒否します。

5秒以内に応答がありません

対話を拒否します。

接続が失敗しました

対話を拒否します。

顧客は、Endpointが失敗したときにトラフィックを許可するようにEnforceモードで外部サービスポリシーを構成することはできません。Log モードでは、Databricks は判定と評価の失敗を記録しますが、強制はしないため、インタラクションがブロックされることはありません。

DatabricksがEndpointを呼び出すとき​

  • Databricksは、ポリシーがランするフェーズごとにEndpointを1回呼び出します(サービスが呼び出される前、応答した後、またはその両方)。両方のフェーズでランするポリシーは、チャットスタイルのモデル対話またはMCPツール呼び出しのために2つのリクエストを送信します。埋め込みの場合、入力フェーズのみがランされます。
  • 顧客がポリシーを Log モードで添付した場合、Databricks は引き続き Endpoint を呼び出して判定を記録しますが、適用はしません。
  • 外部サービスポリシーの前に実行される別のポリシーからのDENYは、DatabricksがEndpointを呼び出す前にインタラクションを停止できます。評価順序を参照してください。

データ処理​

各リクエストには顧客コンテンツが含まれます。モデルのリクエストおよびレスポンスの本文(システムプロンプトや以前のメッセージを含む)、ならびにMCPツールの名前、引数、結果が含まれます。それを顧客データとして扱い、あなたのEndpointが何を、どのくらいの期間、どこで処理するのかを顧客に対して文書化してください。

各外部評価は、呼び出し元が提供したタグを、Log モードを含めて評価者に送信します。タグには機密識別子が含まれる場合があります。外部評価者を構成する際に、このメタデータの開示を顧客と確認してください。

defaultでは、デコードされたタグキーと値の合計サイズは10 KiBのUTF-8データに制限されています。HTTPヘッダーサイズ制限も適用されます。不適切または特大のタグヘッダーは、外部評価の前に拒否されます。モデルリクエストはコード INVALID_PARAMETER_VALUE のHTTP 400 エラーを返し、該当するサービスポリシーを持つMCP tools/call リクエストはJSON-RPC POLICY_DENIED エラー (-32003) のHTTP 200 を返します。この検証は、Logモードでも適用されます。サービスポリシーのリクエストタグを参照してください。

Endpointのテスト​

顧客がEndpointを使用する前に、サンプルリクエストを送信し、5秒以内にALLOW、DENY、またはASKのresultでHTTP 200が返されることを確認します。

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

完全なフローをテストするには、Endpointを使用する外部サービスポリシーをDatabricksワークスペース内のサービスに Log モードでアタッチし、統合トレーステーブルで記録された判定を確認してください。外部サービスポリシーでのパートナーガードレールの適用を参照してください。

次のステップ​