クエリルート最適化サービスエンドポイント

2025-05-30

この記事では、ルート最適化モデルサービスまたは機能サービスエンドポイントに対してクエリを実行できるように、適切な認証資格情報と URL をフェッチする方法について説明します。

要求事項

ルートの最適化が有効になっているエンドポイントまたは機能サービスエンドポイントを提供するモデルについては、「サービスエンドポイントでのルートの最適化」を参照してください。
認証トークン。ルート最適化エンドポイントは OAuth トークンのみをサポートし、個人用アクセストークンはサポートされていません。

最適化されたルートのURLを取得する

ルート最適化エンドポイントを作成すると、エンドポイント用に一意のルート最適化 URL が作成されます。ルート最適化エンドポイントは、専用 URL を使用してのみクエリを実行できます。 URL の形式は次のとおりです。

https://<unique-id>.<shard>.serving.azuredatabricks.net/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

この URL は、次のいずれかから取得できます。

GET /api/2.0/serving-endpoints/{name} API 呼び出しの使用。 URL は、エンドポイントの応答オブジェクトに endpoint_urlとして存在します。このフィールドは、エンドポイントがルート最適化されている場合にのみ設定されます。
サービス UI のサービスエンドポイントの詳細ページ。

ルート最適化エンドポイント URL

OAuth トークンをフェッチし、エンドポイントにクエリを実行する

ルート最適化エンドポイントのクエリを実行するには、OAuth トークンを使用する必要があります。 Databricks では、OAuth トークンをプログラムでフェッチするために、運用アプリケーションでサービスプリンシパルを使用することをお勧めします。次のセクションでは、テストシナリオと運用シナリオで OAuth トークンをフェッチする方法に関する推奨ガイダンスについて説明します。

提供 UI を使用して OAuth トークンを取得する

次の手順は、提供 UI でトークンをフェッチする方法を示しています。これらの手順は、エンドポイントの開発とテストに推奨されます。

アプリケーションでルート最適化エンドポイントを使用する場合と同様に、運用環境で使用する場合は、サービスプリンシパルを使用してトークンがフェッチされます。運用環境のユースケースで OAuth トークンをフェッチするための推奨ガイダンスについては、「OAuth トークンをプログラムでフェッチする」を参照してください。

ワークスペースの [サービス ] UI から:

[提供エンドポイント] ページで、ルート最適化エンドポイントを選択してエンドポイントの詳細を表示します。
エンドポイントの詳細ページで、[ 使用 ] ボタンを選択します。
[トークンのフェッチ] タブを選択します。
[OAuth トークンをフェッチする] ボタンを選択します。このトークンは 1 時間有効です。現在のトークンの有効期限が切れている場合は、新しいトークンをフェッチします。

OAuth トークンをフェッチした後、エンドポイント URL と OAuth トークンを使用してエンドポイントにクエリを実行します。

REST API

REST API の例を次に示します。


URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

Python（プログラミング言語）

Python の例を次に示します。


import requests
import json

url = "<url>"
oauth_token = "<token>"

data = {
    "dataframe_split": {
        "columns": ["feature_1", "feature_2"],
        "data": [
            [0.12, 0.34],
            [0.56, 0.78],
            [0.90, 0.11]
        ]
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {oauth_token}"
}

response = requests.post(url, headers=headers, json=data)

# Print the response
print("Status Code:", response.status_code)
print("Response Body:", response.text)

プログラムで OAuth トークンをフェッチする

運用シナリオの場合、Databricks では、OAuth トークンをプログラムでフェッチするために、アプリケーション内に埋め込むサービスプリンシパルを設定することをお勧めします。これらのフェッチされたトークンは、ルート最適化エンドポイントのクエリに使用されます。

「OAuth を使用してサービスプリンシパルを使用して Azure Databricks リソースへの無人アクセスを承認する」の手順に従って、手順 2. でサービスプリンシパルを作成し、アクセス許可を割り当て、サービスプリンシパルの OAuth シークレットを作成します。サービスプリンシパルが作成されたら、少なくともエンドポイントに対する クエリアクセス許可 をサービスプリンシパルに付与する必要があります。モデルサービスエンドポイントに対するアクセス許可の管理に関するページを参照してください。

Databricks Python SDK には、ルート最適化エンドポイントに直接クエリを実行する API が用意されています。

注

Databricks SDK は Go でも使用できます。 Databricks SDK for Go を参照してください。

この例では、Databricks SDK を使用してルート最適化エンドポイントに対してクエリを実行する必要があります。

サービスエンドポイント名 (SDK は、この名前に基づいて正しいエンドポイント URL をフェッチします)
サービスプリンシパルのクライアント ID
サービスプリンシパルシークレット
ワークスペースのホスト名

クエリの例を次に示します。

from databricks.sdk import WorkspaceClient
import databricks.sdk.core as client

endpoint_name = "<Serving-Endpoint-Name>" ## Insert the endpoint name here

# Initialize Databricks SDK
c = client.Config(
    host="<Workspace-Host>", ## For example, my-workspace.cloud.databricks.com
    client_id="<Client-Id>", ## Service principal ID
    client_secret="<Secret>"   ## Service principal secret
)
w = WorkspaceClient(
    config = c
)

response = w.serving_endpoints_data_plane.query(endpoint_name, dataframe_records = ....)

OAuth トークンを手動でフェッチする

Databricks SDK または Serving UI を使用して OAuth トークンをフェッチできないシナリオでは、OAuth トークンを手動でフェッチできます。このセクションのガイダンスは、主に、ユーザーが運用環境のエンドポイントのクエリに使用するカスタマイズされたクライアントを持っているシナリオに適用されます。

OAuth トークンを手動でフェッチする場合は、要求で authorization_details を指定する必要があります。

<token-endpoint-URL>を Databricks デプロイのワークスペース URL に置き換えて、https://<databricks-instance>を構築します。たとえば、https://<databricks-instance>/oidc/v1/token のようにします。
<client-id>をサービスプリンシパルのクライアント ID (アプリケーション ID とも呼ばれます) に置き換えます。
<client-secret>を、作成したサービスプリンシパルの OAuth シークレットに置き換えます。
<endpoint-id> を、ルート最適化エンドポイントのエンドポイント ID に置き換えます。これは、エンドポイント URL の hostName で見つけることができるエンドポイントの英数字 ID です。
<action> を、サービスプリンシパルに付与されているアクションアクセス許可に置き換えます。アクションには、query_inference_endpoint または manage_inference_endpoint を指定できます。

REST API

REST API の例を次に示します。



export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>
export ENDPOINT_ID=<endpoint-id>
export ACTION=<action>

curl --request POST \
--url <token-endpoint-URL> \
--user "$CLIENT_ID:$CLIENT_SECRET" \
--data 'grant_type=client_credentials&scope=all-apis'
--data-urlencode 'authorization_details=[{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"'"/serving-endpoints/$ENDPOINT_ID"'","actions": ["'"$ACTION"'"]}]'

Python（プログラミング言語）

import os import requests

# Set your environment variables or replace them directly here
CLIENT_ID = os.getenv("CLIENT_ID")
CLIENT_SECRET = os.getenv("CLIENT_SECRET")
ENDPOINT_ID = os.getenv("ENDPOINT_ID")
ACTION = "query_inference_endpoint" # Can also be `manage_inference_endpoint`

# Token endpoint URL
TOKEN_URL = "<token-endpoint-URL>"

# Build the payload, note the creation of authorization_details
payload = { 'grant_type': 'client_credentials', 'scope': 'all-apis', 'authorization_details': f'''[{{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/{ENDPOINT_ID}","actions":["{ACTION}"]}}]''' }

# Make the POST request with basic auth
response = requests.post( TOKEN_URL, auth=(CLIENT_ID, CLIENT_SECRET), data=payload )

# Check the response
if response.ok:
  token_response = response.json()
  access_token = token_response.get("access_token")
  if access_token:
    print(f"Access Token: {access_token}")
  else:
    print("access_token not found in response.")
else: print(f"Failed to fetch token: {response.status_code} {response.text}")

OAuth トークンをフェッチした後、エンドポイント URL と OAuth トークンを使用してエンドポイントにクエリを実行します。

REST API

REST API の例を次に示します。


URL="<endpoint-url>"
OAUTH_TOKEN="<token>"

curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OAUTH_TOKEN" \
  --data "@data.json" \
  "$URL"

Python（プログラミング言語）

Python の例を次に示します。


import requests
import json

url = "<url>"
oauth_token = "<token>"

data = {
    "dataframe_split": {
        "columns": ["feature_1", "feature_2"],
        "data": [
            [0.12, 0.34],
            [0.56, 0.78],
            [0.90, 0.11]
        ]
    }
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {oauth_token}"
}

response = requests.post(url, headers=headers, json=data)

# Print the response
print("Status Code:", response.status_code)
print("Response Body:", response.text)

次の方法で共有

クエリ ルート最適化サービス エンドポイント

要求事項

最適化されたルートのURLを取得する

OAuth トークンをフェッチし、エンドポイントにクエリを実行する

提供 UI を使用して OAuth トークンを取得する

REST API

Python（プログラミング言語）

プログラムで OAuth トークンをフェッチする

OAuth トークンを手動でフェッチする

REST API

Python（プログラミング言語）

REST API

Python（プログラミング言語）

フィードバック

その他のリソース

クエリルート最適化サービスエンドポイント