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

サービス ポリシー関数リファレンス

備考

ベータ版

この機能はプレビューです。ワークスペース管理者は、 プレビュー ページで Unity Gatewayサービスポリシー プレビューを選択して、この機能へのアクセスを制御できます。ワークスペースレベルのプレビューを管理するを参照してください。

カスタムサービスポリシー関数は、Unity Catalog に登録されたユーザー定義関数 (UDF) であり、Databricks はそれが接続されているサービスとの各インタラクションでこれを評価します。このページは、これらの関数のフィールドと構文のリファレンスです。エンドツーエンドの手順については、「SQL ポリシーの作成」を参照してください。

関数シグネチャ​

SQLサービスポリシー関数は、単一のevent VARIANTパラメーターを受け取り、VARIANTを返します。

SQL
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 インタラクションデータとコンテキストを保持します。利用可能なフィールドはサービスタイプによって異なります。

フィールド

適用対象

説明

event:type

すべてのサービス

フェーズ: 'request'(入力、ON CALL)または 'response'(出力、ON RESULT)。

event:target

すべてのサービス

ポリシーがアタッチされているサービスのUnity Catalog完全名 (オプション)。

event:context.request_tags

モデルサービス、モデルプロバイダーサービス、MCPサービス(tools/call)

呼び出し元が指定した文字列のキーと文字列の値を持つ JSON オブジェクト。リクエストタグを参照してください。

event:context.actor.run_as

すべてのサービス

リクエストの認証に使用される実行 ID

event:context.actor.context.is_on_behalf_of

すべてのサービス

true エージェントまたはアプリがユーザーに代わって行動している場合(オン・ビハーフ・オブ、またはOBO)。これを使用して、エージェントがユーザーに代わって行動する場合にのみ適用される、エージェント対応のポリシーを作成します。

event:context.actor.context.client_id

すべてのサービス

アクティングIDのOAuthクライアントID(存在する場合、OBOコール時)。

event:context.actor.context.actor_resource

すべてのサービス

存在する場合、エージェントなどのアクション実行アイデンティティのリソース。

event:context.actor.context.is_actor_authenticated

すべてのサービス

true 実行中のIDが機密クライアントとして認証された場合。

event:context.tool.name, event:context.tool.arguments

MCPサービス

呼び出されているツールとその引数(例:event:context.tool.arguments.repo)。

event:context.message

モデルサービス、モデルプロバイダーサービス

チャット形式のモデル APIs で抽出された最後のユーザーまたはアシスタントのメッセージ(API に依存しません)。このフィールドはエンベディングには存在しません。代わりに event:data.input を読み取ってください。

event:context.conversation.conversation

モデルサービス、モデルプロバイダーサービス

チャットスタイルのモデル APIs のために構成された会話ウィンドウ内のプロバイダーに依存しないメッセージオブジェクトの配列。埋め込みには存在しません。カスタム SQL および Python 関数では、ウィンドウが 1 回に設定されている場合を含め、入力評価と出力評価の両方で使用できます。出力評価では、配列には元のリクエストの会話ウィンドウが含まれます。

event:context.conversation.latest_input

モデルサービス、モデルプロバイダーサービス

埋め込みの場合は該当しませんチャット形式のモデル APIs では、設定されたウィンドウにそのメッセージが含まれていない場合でも、会話全体の最新のユーザーメッセージのテキスト

event:data

モデルサービス、モデルプロバイダーサービス

リクエストまたはレスポンスのペイロード全体。

event:request_data

モデルサービス、モデルプロバイダーサービス

出力フェーズ(ON RESULT)で利用可能な元のリクエスト。

フィールド

適用対象

説明

event:type

すべてのサービス

フェーズ: 'request'(入力、ON CALL)または 'response'(出力、ON RESULT)。

event:target

すべてのサービス

ポリシーがアタッチされているサービスのUnity Catalog完全名 (オプション)。

event:context.request_tags

モデルサービス、モデルプロバイダーサービス、MCPサービス(tools/call)

呼び出し元が指定した文字列のキーと文字列の値を持つ JSON オブジェクト。リクエストタグを参照してください。

event:context.actor.run_as

すべてのサービス

リクエストの認証に使用される実行 ID

event:context.actor.context.is_on_behalf_of

すべてのサービス

true エージェントまたはアプリがユーザーに代わって行動している場合(オン・ビハーフ・オブ、またはOBO)。これを使用して、エージェントがユーザーに代わって行動する場合にのみ適用される、エージェント対応のポリシーを作成します。

event:context.actor.context.client_id

すべてのサービス

アクティングIDのOAuthクライアントID(存在する場合、OBOコール時)。

event:context.actor.context.actor_resource

すべてのサービス

存在する場合、エージェントなどのアクション実行アイデンティティのリソース。

event:context.actor.context.is_actor_authenticated

すべてのサービス

true 実行中のIDが機密クライアントとして認証された場合。

event:context.tool.name, event:context.tool.arguments

MCPサービス

呼び出されているツールとその引数(例:event:context.tool.arguments.repo)。

event:context.message

モデルサービス、モデルプロバイダーサービス

チャット形式のモデル APIs で抽出された最後のユーザーまたはアシスタントのメッセージ(API に依存しません)。このフィールドはエンベディングには存在しません。代わりに event:data.input を読み取ってください。

event:context.conversation.conversation

モデルサービス、モデルプロバイダーサービス

チャットスタイルのモデル APIs のために構成された会話ウィンドウ内のプロバイダーに依存しないメッセージオブジェクトの配列。埋め込みには存在しません。カスタム SQL および Python 関数では、ウィンドウが 1 回に設定されている場合を含め、入力評価と出力評価の両方で使用できます。出力評価では、配列には元のリクエストの会話ウィンドウが含まれます。

event:context.conversation.latest_input

モデルサービス、モデルプロバイダーサービス

埋め込みの場合は該当しませんチャット形式のモデル APIs では、設定されたウィンドウにそのメッセージが含まれていない場合でも、会話全体の最新のユーザーメッセージのテキスト

event:data

モデルサービス、モデルプロバイダーサービス

リクエストまたはレスポンスのペイロード全体。

event:request_data

モデルサービス、モデルプロバイダーサービス

出力フェーズ(ON RESULT)で利用可能な元のリクエスト。

注記

パスアクセス (event:...) は VARIANT を返します。スカラー型にキャストしてからリテラルと比較します (例えば、event:type::string = 'request')。そうしないと、比較は DATATYPE_MISMATCH エラーで失敗します。

会話コンテキスト​

チャットスタイルのモデル API を評価するカスタム SQL または Python 関数では、会話ウィンドウを構成できます。1 ターンを含む構成済み値の場合、event:context.conversation には、入力評価と出力評価の両方で、このプロバイダーに依存しない形状があります。出力評価中、このオブジェクトには元のリクエストの会話が含まれます。

JSON
{
"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ヘッダーで送信されたタグを評価できます。

HTTP
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)はサポートされていません。

SQL
to_variant_object(named_struct('result', 'DENY', 'reason', 'GitHub push operations are not permitted by policy.'))

ゲートウェイは、将来を見据えたエンベロープ形式も受け入れます。

SQL
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 互換性をチェックするため、ポリシーをアタッチして本体がサポートされていることを確認します。

カテゴリー

ポリシー本文でサポートされています

演算子

比較演算子、論理演算子、および算術演算子、||、IN、LIKE IS [NOT] NULL

コントロールフロー

CASE そして IF

キャスト

CAST INT/BIGINT、DOUBLE/FLOAT、STRING、またはBOOLEANへ;::演算子

データアクセス

VARIANT / JSON パス アクセス

文字列関数

CONCAT、LENGTH、CHAR_LENGTH、UPPER、LOWER、SUBSTRING、TRIM、LTRIM、RTRIM、REPLACE、STARTSWITH、ENDSWITH、 CONTAINS

その他の機能

COALESCE、NULLIF、IFNULL、NVL、ABS、MOD、ISNULL、ISNOTNULL、NAMED_STRUCT、 TO_VARIANT_OBJECT

カテゴリー

ポリシー本文でサポートされています

演算子

比較演算子、論理演算子、および算術演算子、||、IN、LIKE IS [NOT] NULL

コントロールフロー

CASE そして IF

キャスト

CAST INT/BIGINT、DOUBLE/FLOAT、STRING、またはBOOLEANへ;::演算子

データアクセス

VARIANT / JSON パス アクセス

文字列関数

CONCAT、LENGTH、CHAR_LENGTH、UPPER、LOWER、SUBSTRING、TRIM、LTRIM、RTRIM、REPLACE、STARTSWITH、ENDSWITH、 CONTAINS

その他の機能

COALESCE、NULLIF、IFNULL、NVL、ABS、MOD、ISNULL、ISNOTNULL、NAMED_STRUCT、 TO_VARIANT_OBJECT

サポートされていません: ai_query、サブクエリ、BETWEEN、集計関数、ラムダ / EXISTS、および可変長引数 CONCAT または COALESCE。

NULL処理関数​

COALESCE、IFNULL、NVL、ISNULL、およびISNOTNULLは、呼び出し内で最初の引数をSTRINGにキャストすると、たとえばevent:context.message::STRINGのようにCEL検証に失敗します。代わりに、イベントフィールドをVARIANT値として渡してください。COALESCE、IFNULL、NVLの場合は、結果をキャストしてください:

CEL検証に失敗します

CEL検証を通過

COALESCE(event:context.message::STRING, '')

CAST(COALESCE(event:context.message, '') AS STRING)

IFNULL(event:context.message::STRING, '')

CAST(IFNULL(event:context.message, '') AS STRING)

NVL(event:context.message::STRING, '')

CAST(NVL(event:context.message, '') AS STRING)

ISNULL(event:context.message::STRING)

ISNULL(event:context.message)

ISNOTNULL(event:context.message::STRING)

ISNOTNULL(event:context.message)

CEL検証に失敗します

CEL検証を通過

COALESCE(event:context.message::STRING, '')

CAST(COALESCE(event:context.message, '') AS STRING)

IFNULL(event:context.message::STRING, '')

CAST(IFNULL(event:context.message, '') AS STRING)

NVL(event:context.message::STRING, '')

CAST(NVL(event:context.message, '') AS STRING)

ISNULL(event:context.message::STRING)

ISNULL(event:context.message)

ISNOTNULL(event:context.message::STRING)

ISNOTNULL(event:context.message)

fallbackには、'' のようなリテラル、または別のイベントフィールドを指定できます。COALESCE には、引数を正確に 2 つ指定する必要があります。

NULLIF たとえば NULLIF(event:context.message::STRING, 'n/a') のように、最初の引数が STRING にキャストされた場合、CELバリデーションも失敗します。

欠落しているフィールドはNULLとして読み取られるため、これらの関数はオプションのフィールドを処理できます。たとえば、projectタグのないリクエストにはevent:context.request_tags.projectフィールドがないため、次の条件は真になります。

SQL
CAST(COALESCE(event:context.request_tags.project, '') AS STRING) = ''

関連​