サービス ポリシー関数リファレンス
ベータ版
この機能はプレビューです。ワークスペース管理者は、 プレビュー ページで 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>;
チャットスタイルのモデル APIs と MCP ツール呼び出しの場合、関数は両方の評価ポイントでランします。event:type::stringのBranchでそれらを区別します:
'request':入力フェーズ(ON CALL)、サービスが呼び出される前。'response': サービスが応答した後の出力フェーズ(ON RESULT)。
埋め込みリクエストの場合、関数は 'request' イベントのみを受け取り、event:data.input から入力を読み取ります。埋め込みベクトルを検査しません。Responses APIs も event:data.input を使用するため、その存在だけでは埋め込みリクエストを識別できません。ポリシーを埋め込みにのみ適用する必要がある場合は、別のサービスを使用します。
event 引数
event インタラクションデータとコンテキストを保持します。利用可能なフィールドはサービスタイプによって異なります。
フィールド | 適用対象 | 説明 |
|---|---|---|
| すべてのサービス | フェーズ: |
| すべてのサービス | ポリシーがアタッチされているサービスのUnity Catalog完全名 (オプション)。 |
| モデルサービス、モデルプロバイダーサービス、MCPサービス( | 呼び出し元が指定した文字列のキーと文字列の値を持つ JSON オブジェクト。リクエストタグを参照してください。 |
| すべてのサービス | リクエストの認証に使用される実行 ID |
| すべてのサービス |
|
| すべてのサービス | アクティングIDのOAuthクライアントID(存在する場合、OBOコール時)。 |
| すべてのサービス | 存在する場合、エージェントなどのアクション実行アイデンティティのリソース。 |
| すべてのサービス |
|
| MCPサービス | 呼び出されているツールとその引数(例: |
| モデルサービス、モデルプロバイダーサービス | チャット形式のモデル APIs で抽出された最後のユーザーまたはアシスタントのメッセージ(API に依存しません)。このフィールドはエンベディングには存在しません。代わりに |
| モデルサービス、モデルプロバイダーサービス | チャットスタイルのモデル APIs のために構成された会話ウィンドウ内のプロバイダーに依存しないメッセージオブジェクトの配列。埋め込みには存在しません。カスタム SQL および Python 関数では、ウィンドウが 1 回に設定されている場合を含め、入力評価と出力評価の両方で使用できます。出力評価では、配列には元のリクエストの会話ウィンドウが含まれます。 |
| モデルサービス、モデルプロバイダーサービス | 埋め込みの場合は該当しませんチャット形式のモデル APIs では、設定されたウィンドウにそのメッセージが含まれていない場合でも、会話全体の最新のユーザーメッセージのテキスト |
| モデルサービス、モデルプロバイダーサービス | リクエストまたはレスポンスのペイロード全体。 |
| モデルサービス、モデルプロバイダーサービス | 出力フェーズ(ON RESULT)で利用可能な元のリクエスト。 |
パスアクセス (event:...) は VARIANT を返します。スカラー型にキャストしてからリテラルと比較します (例えば、event:type::string = 'request')。そうしないと、比較は DATATYPE_MISMATCH エラーで失敗します。
会話コンテキスト
チャットスタイルのモデル API を評価するカスタム 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は対話をブロックします。チャットスタイルのモデル APIs の場合、呼び出し元はエラーではなく成功 (HTTP 200) 応答を受け取ります。モデルサービスまたはモデルプロバイダーサービスのAPIの場合、アシスタントのターンはブロックを報告し、reasonは最上位のdatabricks_service_policyオブジェクトにあります。埋め込み拒否は、モデルがランされる前に、リクエスト全体に対してHTTP 400を返します。MCPサービスでは、応答はerror.messageにreasonを含むJSON-RPCエラーです。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) = ''