サービス ポリシー関数リファレンス
ベータ版
この機能はプレビューです。ワークスペース管理者は、 プレビュー ページで Unity Gatewayサービスポリシー プレビューを選択して、この機能へのアクセスを制御できます。ワークスペースレベルのプレビューを管理するを参照してください。
カスタムサービスポリシー関数は、Unity Catalog に登録されたユーザー定義関数 (UDF) であり、Databricks はそれが接続されているサービスとの各インタラクションでこれを評価します。このページは、これらの関数のフィールドと構文のリファレンスです。エンドツーエンドの手順については、「SQL ポリシーの作成」を参照してください。
関数シグネチャ
SQLサービスポリシー関数は、単一のevent VARIANTパラメーターを受け取り、VARIANTを返します。
CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;
この関数は両方の評価ポイントで実行されます。それらを区別するためにevent:type::stringで分岐します。
'request':入力フェーズ(ON CALL)、サービスが呼び出される前。'response': サービスが応答した後の出力フェーズ(ON RESULT)。
event 引数
event インタラクションデータとコンテキストを保持します。利用可能なフィールドはサービスタイプによって異なります。
フィールド | 適用対象 | 説明 |
|---|---|---|
| すべてのサービス | フェーズ: |
| すべてのサービス | ポリシーがアタッチされているサービスのUnity Catalog完全名 (オプション)。 |
| モデルサービス、モデルプロバイダーサービス、MCPサービス( | 呼び出し元が指定した文字列のキーと文字列の値を持つ JSON オブジェクト。リクエストタグを参照してください。 |
| すべてのサービス | リクエストの認証に使用される実行 ID |
| すべてのサービス |
|
| すべてのサービス | アクティングIDのOAuthクライアントID(存在する場合、OBOコール時)。 |
| すべてのサービス | 存在する場合、エージェントなどのアクション実行アイデンティティのリソース。 |
| すべてのサービス |
|
| MCPサービス | 呼び出されているツールとその引数(例: |
| モデルサービス、モデルプロバイダーサービス | 抽出された最後のユーザーまたはアシスタントメッセージ(API非依存)。コンテンツの確認にご利用ください。 |
| モデルサービス、モデルプロバイダーサービス | 構成された会話ウィンドウ内のプロバイダーに中立的なメッセージオブジェクトの配列。ウィンドウが1ターンに設定されている場合を含め、入力と出力の両方の評価中にカスタム SQL と Python 関数で利用できます。出力評価中に、配列には元のリクエストの会話ウィンドウが含まれます。 |
| モデルサービス、モデルプロバイダーサービス | 設定されたウィンドウにそのメッセージが含まれていない場合でも、会話全体における直近のユーザーメッセージのテキスト。 |
| モデルサービス、モデルプロバイダーサービス | リクエストまたはレスポンスのペイロード全体。 |
| モデルサービス、モデルプロバイダーサービス | 出力フェーズ(ON RESULT)で利用可能な元のリクエスト。 |
パスアクセス (event:...) は VARIANT を返します。スカラー型にキャストしてからリテラルと比較します (例えば、event:type::string = 'request')。そうしないと、比較は DATATYPE_MISMATCH エラーで失敗します。
会話コンテキスト
モデル サービスまたはモデル プロバイダー サービスに接続されたカスタム SQL または Python 関数の場合、会話ウィンドウを設定できます。1ターンを含む設定値の場合、event:context.conversation は入力評価と出力評価の両方で、このプロバイダーに依存しない形式になります。出力評価中、オブジェクトには元のリクエストの会話が含まれます。
{
"conversation": [
{ "role": "user", "content": "First question" },
{ "role": "assistant", "content": "First answer" },
{ "role": "user", "content": "Follow-up question" }
],
"latest_input": "Follow-up question"
}
conversation 配列には、構成されたウィンドウが含まれています。latest_inputには、そのメッセージがウィンドウの外にある場合でも、完全な会話からの最新のユーザーメッセージが含まれます。ワークスペースでマルチターン会話コンテキストが無効になっている場合、構成されたすべてのウィンドウは 1 つのターンとして扱われます。
ゲートウェイは event:context.message と event:data を保持するため、既存の関数は引き続き単一の抽出メッセージと完全なプロバイダーペイロードを受け取ります。ウィンドウが未設定の場合やMCPサービスの場合、会話オブジェクトは追加されません。
タグのリクエスト
カスタムポリシーによって、Databricks-Ai-Gateway-Request-Tagsヘッダーで送信されたタグを評価できます。
Databricks-Ai-Gateway-Request-Tags: {"project":"p-1042"}
このサポートは、MCP tools/call を含め、サービスポリシーが実行されるパス上の Unity Gateway リクエストに適用されます。
タグはリクエストヘッダーから取得され、他のポリシーメタデータとともに event:context に表示されます。event:data および event:request_data には、ペイロード本体が含まれます。
event:context.request_tags は event VARIANT 内のオブジェクトであり、文字列のキーと文字列の値を持ち、論理的には MAP<STRING, STRING> です。event:context.request_tags.project::string を使用してタグを読み取ります。キーと値は、大文字と小文字、句読点、および空の文字列を保持します。ヘッダーのないリクエストには、空のオブジェクト({})が含まれます。両方の評価フェーズは、リクエスト変換、リトライ、モデルfallbackを含め、同じリクエストタグを受け取ります。
defaultでは、デコードされたキーと値の合計サイズは 10 KiB の UTF-8 データに制限されます。HTTP ヘッダーのサイズ制限も適用されます。SDK および REST の例については、リクエストのタグ付けを参照してください。
モデルサービスは、不正な形式またはサイズオーバーのタグヘッダーを拒否します。適用可能なサービスポリシーが設定された MCP tools/call リクエストの場合、ゲートウェイはポリシーを評価する前( Log モードを含む)にこれらのヘッダーも拒否します。
タグは呼び出し元から提供されるものであり、サービスタグや認証済みアクターのコンテキストとは別個のものです。タグ単体では、IDやプロジェクトを使用する権限は確立されません。これらの権限を確認する際は、信頼できるIDおよび認可データを使用してください。タグ値の確認例については、適格なプロジェクトの要件を参照してください。
次の制限が適用されます:
- リクエストタグはLLM-as-a-judgeのプロンプトに自動的に追加されません。外部サービス ポリシー API リファレンスに記載されているとおり、外部サービスのポリシーにはこれらが渡されます。
- MCPの
ASK承認ではリクエストのタグが区別されず、承認プロンプトにも表示されません。タグが異なっていても、それ以外が一致する呼び出しに対して承認を再利用できます。タグベースの適用にはALLOWおよびDENYの決定を使用します。これらの決定は、各リクエストに対して評価されます。
戻り値
カスタムSQLポリシーはDecision ポリシーです。resultフィールドの値がALLOW、DENY、またはASK(大文字と小文字を区別しない)で、任意のreasonを含むVARIANTを返します。resultの値によって、処理が決まります:
ALLOW:対話が進行します。DENY:Databricks は対話をブロックします。エラーの代わりに、呼び出し元は成功 (HTTP 200) 応答を受け取ります。Model サービス または Model Provider サービス では、アシスタントのターンはブロックを報告し、reasonはトップレベルのdatabricks_service_policyオブジェクトにあります。MCP サービスでは、応答は JSON-RPC エラーで、reasonはerror.messageにあります。ASK:MCP サービスの場合、ツールが実行される前にリクエストはユーザーの承認を待機します。カスタム ポリシー関数がモデル サービスまたはモデル プロバイダー サービスに対してASKを返す場合、これらのサービスはユーザーに承認を求めることができないため、Databricks はリクエストまたはレスポンスをブロックします。
named_structで結果を構築し、関数がVARIANTを返すようにto_variant_objectでラップし、resultとreasonをトップレベルフィールドとして保持します。単純なnamed_structはSTRUCTを返しますが、CAST(... AS VARIANT)はサポートされていません。
to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))
ゲートウェイは、将来を見据えたエンベロープ形式も受け入れます。
to_variant_object(named_struct('decision', named_struct('result', 'DENY', 'reason', '...')))
VARIANTパラメーターに存在しないフィールドは、標準のSQL VARIANTアクセスと同様にNULLとして読み取られます。=、<、INなどの欠損フィールドを読み取る比較はエラーを発生させ、DENYになります。これにより、予期されるフィールドが欠落している場合に、ポリシーがインタラクションを許可するのを防ぎます。欠落している可能性のあるフィールドを処理するには、ISNULLやCOALESCEなどのnull処理関数を使用します。「Null処理関数」を参照してください。
サポートされている SQL
Databricks はポリシー本文を CEL にトランスパイルし、ランタイム時に評価するため、関数本体は SQL の制限されたサブセットのみをサポートします。Databricks は、ポリシーをアタッチするときにサポートされていない関数や構成をエラー policy function '<name>' SQL cannot be transpiled to CEL で拒否し、評価時にポリシーはクローズ (DENY) で失敗します。関数を作成して Test function で実行すると、本文が SQL としてのみチェックされます。Databricks はポリシーをアタッチするときに CEL 互換性をチェックするため、ポリシーをアタッチして本体がサポートされていることを確認します。
カテゴリー | ポリシー本文でサポートされています |
|---|---|
演算子 | 比較演算子、論理演算子、および算術演算子、 |
コントロールフロー |
|
キャスト |
|
データアクセス | VARIANT / JSON パス アクセス |
文字列関数 |
|
その他の機能 |
|
サポートされていません: ai_query、サブクエリ、BETWEEN、集計関数、ラムダ / EXISTS、および可変長引数 CONCAT または COALESCE。
NULL処理関数
COALESCE、IFNULL、NVL、ISNULL、およびISNOTNULLは、呼び出し内で最初の引数をSTRINGにキャストすると、たとえばevent:context.message::STRINGのようにCEL検証に失敗します。代わりに、イベントフィールドをVARIANT値として渡してください。COALESCE、IFNULL、NVLの場合は、結果をキャストしてください:
CEL検証に失敗します | CEL検証を通過 |
|---|---|
|
|
|
|
|
|
|
|
|
|
fallbackには、'' のようなリテラル、または別のイベントフィールドを指定できます。COALESCE には、引数を正確に 2 つ指定する必要があります。
NULLIF たとえば NULLIF(event:context.message::STRING, 'n/a') のように、最初の引数が STRING にキャストされた場合、CELバリデーションも失敗します。
欠落しているフィールドはNULLとして読み取られるため、これらの関数はオプションのフィールドを処理できます。たとえば、projectタグのないリクエストにはevent:context.request_tags.projectフィールドがないため、次の条件は真になります。
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''