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

Important

この機能は ベータ版です。 ワークスペース管理者は、Unityゲートウェイサービスポリシープレビューに参加することで、プレビューページからこの機能へのアクセスをコントロールできます。 ワークスペース レベルのプレビューの管理を参照してください。

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

Pythonのポリシー関数については、「Python ポリシー関数」および「カスタムPythonサービスポリシーを書く」を参照してください。

関数のシグネチャ

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

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT
)
RETURNS VARIANT
LANGUAGE SQL
RETURN <expression>;

この関数は両方の評価ポイントで実行されます。 event:type::string上で分岐して、それらを区別します。

  • 'request'サービスが呼び出される前に入力フェーズ(オンコール)を行います。
  • 'response':サービスが応答した後の出力位相(ON RESULT)です。

event引数

event は相互作用データとコンテキストを運びます。 使用可能なフィールドは、サービスの種類によって異なります。

フィールド 適用対象 説明
event:type すべてのサービス 位相: 'request' (入力、オンコール)または 'response' (出力、オン・リザルト)。
event:target すべてのサービス ポリシーがアタッチされているサービスの Unity カタログの完全な名前 (省略可能)。
event:context.request_tags モデルサービス、モデルプロバイダーサービス、MCPサービス(tools/call) 呼び出し元が提供する文字列キーと文字列値のJSONオブジェクトです。 リクエスト タグを参照してください。
event:context.actor.run_as すべてのサービス 要求が承認する実行 ID。
event:context.actor.context.is_on_behalf_of すべてのサービス true エージェントやアプリがユーザーの代理として行動している場合(on-besign-of、OBO)。 これを使用して、エージェントがユーザーに対して機能する場合にのみ適用されるエージェント対応ポリシーを記述します。
event:context.actor.context.client_id すべてのサービス 動作する ID の OAuth クライアント ID (存在する場合 ) (OBO 呼び出し)。
event:context.actor.context.actor_resource すべてのサービス エージェントなどの動作 ID のリソース (存在する場合)。
event:context.actor.context.is_actor_authenticated すべてのサービス true 代理の身元が機密クライアントとして認証されたとき。
event:context.tool.name、event:context.tool.arguments MCP サービス 呼び出されるツールとその引数 ( event:context.tool.arguments.repoなど)。
event:context.message モデル サービス、モデル プロバイダー サービス 抽出された最後のユーザーまたはアシスタント メッセージ (API に依存しない)。 これはコンテンツ チェックに使用します。
event:context.conversation.conversation モデル サービス、モデル プロバイダー サービス 構成された会話ウィンドウ内のプロバイダーニュートラルメッセージオブジェクトの配列です。 入力および出力の評価中、ウィンドウが1ターンに設定されている場合も含め、カスタムSQLおよびPython関数で利用可能です。 出力評価時には、配列には発信要求の会話ウィンドウが含まれます。
event:context.conversation.latest_input モデル サービス、モデル プロバイダー サービス 構成済みウィンドウでそのメッセージを除外しても、会話全体に含まれている最新のユーザーメッセージのテキストです。
event:data モデル サービス、モデル プロバイダー サービス 要求または応答の完全なペイロード。
event:request_data モデル サービス、モデル プロバイダー サービス 出力フェーズ中に利用可能な元のリクエスト(ON RESULT)です。

Note

パス アクセス (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"}

このサポートは、サービスポリシーが実行されるパス上のUnity Gatewayリクエスト(MCP tools/callを含む)に適用されます。

タグはリクエストヘッダーから来て、他のポリシーメタデータとともに event:context に表示されます。 event:data event:request_dataはペイロードの遺体を含んでいます。

event:context.request_tags は eventVARIANT内のオブジェクトで、文字列キーと文字列値を持ち、論理的に MAP<STRING, STRING>。 タグを読んで event:context.request_tags.project::string。 キーと値は大文字、句読点、空文字列を保持します。 ヘッダーのないリクエストは空のオブジェクト({})を持ちます。 両評価フェーズは、リクエスト変換、リトライ、モデルのフォールバックを通じて同じリクエストタグを受け取ります。

デフォルトでは、デコードされたキーと値の合計サイズは10 KiBのUTF-8データに制限されています。 HTTPヘッダーのサイズ制限も適用されます。 SDKおよびRESTの例については 「リクエストタグ付け」を参照してください。

モデルサービスは、形が悪くなっているタグヘッダーや過大なタグヘッダーを拒否します。 適用されるサービスポリシーを持つMCP tools/call リクエストの場合、ゲートウェイはこれらのヘッダーをポリシー評価前に拒否します( ログ モードも含む)。

タグは発信者によって提供され、サービスタグや認証されたアクターコンテキストとは別に存在します。 タグだけでは、プロジェクトのアイデンティティや使用許可を確立するものではありません。 権限を確認する際には信頼できるIDおよび認証データを使用してください。 タグ値の確認例は「 対象プロジェクトを要求する」 を参照してください。

次の制限事項が適用されます。

  • リクエストタグは、外部ポリシー提供者に送信されるイベントや、LLMの判定者プロンプトに自動的に追加されることはありません。
  • MCP ASK 承認はリクエストタグを区別せず、承認プロンプトも表示しません。 承認は、異なるタグで一致する通話でも再利用できます。 タグベースの強制には ALLOW および DENY 決定を活用しましょう。 これらの決定は各要請ごとに評価されます。

値を返す

カスタムSQLポリシーはDecision Policy(決定ポリシー)であり、ALLOW、DENY、またはASK(大文字を区別しない)resultフィールドとオプションのreasonを持つVARIANTを返します。 result値は、何が起こるかを決定します。

  • ALLOW:相互作用は進行します。
  • DENY: Azure Databricks はこの相互作用をブロックします。 エラーの代わりに、呼び出し元は成功した(HTTP 200)応答を受け取ります。 モデルサービスまたはモデルプロバイダーサービスでは、アシスタントターンがブロックを報告し、 reason はトップレベルの databricks_service_policy オブジェクトに含まれています。 MCPサービスでは、応答は JSON-RPC エラーで reason が error.messageに入っています。
  • ASK: MCPサービスでは、ツールが実行される前にリクエストがユーザーの承認のために一時停止されます。 カスタムポリシー関数がモデルサービスまたはモデルプロバイダーサービスのASKを返した場合、Azure Databricksはリクエストやレスポンスをブロックします。なぜなら、これらのサービスはユーザーに承認を求めることができないからです。

named_structを使用して結果をビルドし、to_variant_objectでラップして、VARIANTと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', '...')))

Note

VARIANTパラメータに存在しないフィールドは、標準的なSQL VARIANTアクセスと同様にNULLとして読み取られます。 =、<、INなどの欠損フィールドを読み取る比較は誤差が生じ、DENYとなります。 これにより、予期されるフィールドがない場合に、ポリシーで対話が許可されなくなります。 欠損している可能性のあるフィールドを処理するには、 ISNULL や COALESCEのようなヌル処理関数を使いましょう。 参照: Null-ハンドリング関数。

Pythonポリシー関数

Pythonポリシー関数は、eventとconfigの2つのVARIANTパラメータを受け取り、VARIANTを返します。

CREATE OR REPLACE FUNCTION <catalog>.<schema>.<function_name>(
  event VARIANT,
  config VARIANT
)
RETURNS VARIANT
LANGUAGE PYTHON
ENVIRONMENT (environment_version = '6')
AS $$
  <function body>
$$;
  • eventはeventの引数に記載されているフィールドを持ちます。 PythonではtoPython()で変換し、辞書キーと同じフィールドを読みます。 例えば、SQLのevent:context.tool.nameはPythonでevent_value.get("context", {}).get("tool", {}).get("name")されます。
  • config ポリシーの添付ファイルに保存されたオプションを保持するか、オプションがない場合は空のオブジェクトを保持します。 関数は使わなくても宣言しなければなりません。
  • この関数は、decisionオブジェクトを保持するVARIANTを返します。resultはALLOW、DENY、またはASK(大文字に区別されません)で、オプションのreasonも含まれます。
import json

def policy_decision(result, reason=""):
    return type(event).parseJson(json.dumps({"decision": {"result": result, "reason": reason}}))

event_value = event.toPython() if hasattr(event, "toPython") else event
if event_value.get("type") == "request" and "confidential" in str(event_value.get("context", {}).get("message", "")).lower():
    return policy_decision("DENY", "Requests about confidential projects are not allowed.")
return policy_decision("ALLOW")

サポートされているSQL制限はPython関数には適用されません。関数はUnity CatalogのPython UDFとして動作し、Python標準ライブラリと宣言された依存関係を使用できます。 []で欠損フィールドを読み取る際のKeyErrorのような処理されていない例外は、この相互作用を否定します。 オプション欄は get()で読みます。 要件、依存関係、サービス認証情報、制限については「カスタムPythonサービスポリシーを書く」を参照してください。

サポートされている SQL

Azure Databricks、ポリシー本体を CEL にトランスパイルし、実行時に評価するため、関数本体は SQL の制限されたサブセットのみをサポートします。 ポリシーを付け付けると、エラーpolicy function '<name>' SQL cannot be transpiled to CELでAzure Databricksサポートされていない関数や構成文を拒否し、評価時にポリシーが閉じられ(DENY)失敗します。 関数を作成して テスト関数 で実行すると、本文はSQLのみとして確認してください。 Azure Databricksはポリシーを付けるとCEL互換性をチェックしますので、ポリシーを添付して本体がサポートされているか確認してください。

Category ポリシー本文でサポートされます
Operators 比較演算子、論理演算子、および算術演算子。 \|\|、 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。

ヌルハンドリング関数

COALESCE、IFNULL、NVL、ISNULL、ISNOTNULLは、例えばevent:context.message::STRINGなど、最初の引数がコール内で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)

フォールバックは ''のようなリテラルでも、他のイベントフィールドでもよい。 COALESCE は正確に2つの引数を受け入れます。

NULLIF また、最初の引数が STRINGにキャストされた場合、例えば NULLIF(event:context.message::STRING, 'n/a')でCEL検証に失敗します。

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

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