ルート最適化されたサービスエンドポイントをクエリする
この記事では、ルート最適化モデルサービングエンドポイントをクエリできるように、適切な認証資格情報と URL を取得する方法について説明します。
必要条件
- ルート最適化が有効になっているモデルサービングエンドポイントについては、「 サービスエンドポイントでのルート最適化」を参照してください。
- ルート最適化されたエンドポイントのクエリでは、OAuth トークンの使用のみがサポートされます。個人的なアクセスはサポートされていません。
クイックスタート: エンドツーエンドのクエリーレシピ
次のレシピでは、外部クライアントからルート最適化されたエンドポイントにクエリーを実行するために必要なすべてのステップを単一の実行可能なフローに統合します。作業中のセットアップを迅速に検証したい場合は、このセクションを使用してください。各ステップの詳細については、次のセクションを参照してください。
# 1. Set the variables for your environment.
export DATABRICKS_HOST="https://<your-workspace>.cloud.databricks.com"
export ENDPOINT_NAME="<your-endpoint>"
export WORKSPACE_ID="<workspace-id>"
# 2. Create an account-level service principal and an OAuth secret for it.
SP_ID=$(databricks account service-principals create \
--json '{"displayName":"my-app","active":true}' --output json | jq -r '.id')
SECRET_JSON=$(databricks account service-principal-secrets create "$SP_ID" --output json)
export CLIENT_ID=$(databricks account service-principals get "$SP_ID" --output json | jq -r '.applicationId')
export CLIENT_SECRET=$(echo "$SECRET_JSON" | jq -r '.secret')
# 3. Assign the service principal to the workspace and grant CAN_QUERY on the endpoint.
databricks account workspace-assignment update "$WORKSPACE_ID" "$SP_ID" \
--json '{"permissions":["USER"]}'
ENDPOINT_ID=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.id')
databricks permissions update serving-endpoints "$ENDPOINT_ID" \
--json "{\"access_control_list\":[{\"service_principal_name\":\"$CLIENT_ID\",\"permission_level\":\"CAN_QUERY\"}]}"
# 4. Mint an endpoint-scoped OAuth token. `authorization_details` is required for
# route-optimized endpoints -- a plain `scope=all-apis` token is rejected with
# 401 "Missing authorization details" when used against the route-optimized URL.
TOKEN=$(curl -sS -X POST -u "$CLIENT_ID:$CLIENT_SECRET" \
--data-urlencode "grant_type=client_credentials" \
--data-urlencode "scope=all-apis" \
--data-urlencode "authorization_details=[{\"type\":\"workspace_permission\",\"object_type\":\"serving-endpoints\",\"object_path\":\"/serving-endpoints/$ENDPOINT_ID\",\"actions\":[\"query_inference_endpoint\"]}]" \
"$DATABRICKS_HOST/oidc/v1/token" | jq -r '.access_token')
# 5. Invoke the endpoint at its route-optimized URL.
RO_URL=$(databricks serving-endpoints get "$ENDPOINT_NAME" --output json | jq -r '.endpoint_url')
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"inputs":[[0.12,0.34]]}' "https://$RO_URL"
ルート最適化されたURLを取得する
2025 年 9 月 22 日 以降、新しく作成されたすべてのルート最適化エンドポイントは、ルート最適化 URL を通じてのみクエリされる必要があります。この日付以降に作成されたエンドポイントは、ワークスペース URL を介したクエリをサポートしません。
ルート最適化エンドポイント が 2025 年 9 月 22 日より前に 作成された場合:
-
標準のワークスペース URL を使用してエンドポイントをクエリすることもできます。標準のワークスペース URL パスでは、ルート最適化の利点は得られ ません 。
https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations -
この日付より前に作成されたルート最適化エンドポイントは、引き続き両方の呼び出し URL (ルート最適化 URL パスと標準ワークスペース URL パス) をサポートします。
ルート最適化エンドポイントを作成すると、エンドポイントに対して次のルート最適化 URL が作成されます。
https://<unique-id>.serving.gcp.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations
この URL は以下から取得できます。
- Serving UI
- REST API
- Databricks SDK
GET /api/2.0/serving-endpoints/{name} API 呼び出しを使用します。URL はエンドポイントの応答オブジェクト内にendpoint_urlとして存在します。このフィールドは、エンドポイントがルート最適化されている場合にのみ入力されます。
GET /api/2.0/serving-endpoints/my-endpoint
{
"name": "my-endpoint"
}
Serving Endpoints API get呼び出しを使用します。URL はエンドポイントの応答オブジェクト内にendpoint_urlとして存在します。このフィールドは、エンドポイントがルート最適化されている場合にのみ入力されます。
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()
workspace.serving_endpoints.get("my-endpoint")
OAuth トークンをフェッチし、エンドポイントをクエリする
ルート最適化されたエンドポイントをクエリするには、OAuth トークンを使用する必要があります。Databricks 、本番運用アプリケーションでサービスプリンシパルを使用して、プログラムでOAuthセキュリティを取得することをお勧めします。 次のセクションでは、テストおよび本番運用シナリオでOAuth取得する方法に関する推奨ガイダンスについて説明します。
Serving UI を使用した OAuth トークンの取得
次の手順は、Serving UI でトークンをフェッチする方法を示しています。これらの手順は、エンドポイントの開発とテストに推奨されます。
アプリケーションでルート最適化エンドポイントを使用する場合など、本番運用で使用する場合は、サービス プリンシパルを使用して Windows が取得されます。 本番運用のユースケースでOAuthトークンを取得するための推奨ガイダンスについては、「プログラムでOAuthトークンを取得する」を参照してください。
ワークスペースの Serving UI から:
- [サービス エンドポイント] ページで、ルート最適化されたエンドポイントを選択して、エンドポイントの詳細を表示します。
- エンドポイントの詳細ページで、 [使用 ] ボタンを選択します。
- [トークンの取得 ] タブを選択します。
- OAuth トークンの取得 ボタンを選択します。このトークンは1時間有効です。 現在のトークンの有効期限が切れた場合は、新しいトークンをフェッチします。
OAuth トークンをフェッチしたら、エンドポイント URL と OAuth トークンを使用してエンドポイントをクエリします。
- REST API
- Python
次に、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 の例を示します。
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を使用した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>を作成するには、https://<databricks-instance>を Databricks デプロイのワークスペース URL に置き換えますhttps://<databricks-instance>/oidc/v1/token。例えばhttps://my-workspace.gcp.databricks.com/oidc/v1/token -
<client-id>をサービスプリンシパルのクライアント ID (アプリケーション ID とも呼ばれます) に置き換えます。 -
<client-secret>を、作成したサービスプリンシパルの OAuth シークレットに置き換えます。 -
<endpoint-id>ルート最適化エンドポイントのエンドポイント ID に置き換えます。これは、エンドポイント URL のhostNameにあるエンドポイントの英数字 ID です。たとえば、サービスエンドポイントがhttps://abcdefg.serving.gcp.databricks.com/9999999/serving-endpoints/testの場合、エンドポイント ID はabcdefgになります。 -
<action>を、サービスプリンシパルに付与されたアクション権限に置き換えます。アクションはquery_inference_endpointまたはmanage_inference_endpointにすることができます。
- REST API
- Python
次に、REST API の例を示します。
export CLIENT_ID=<client-id>
export CLIENT_SECRET=<client-secret>
export ENDPOINT_ID=<endpoint-id>
export ACTION=<action> # for example, 'query_inference_endpoint'
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
- Python
次に、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 の例を示します。
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)
AIエージェントまたは外部アプリケーションからの呼び出し
ルート最適化されたエンドポイントにクエリーを実行するAIコーディングアシスタントおよび外部アプリケーションは、開発者の個人アクセストークンまたはワークスペースのOAuthトークンを使用できません。OAuth M2Mフローを使用してサービスプリンシパルを使用し、トークンリクエストにauthorization_detailsを含める必要があります。フローは次のとおりです:
- アカウントレベルでサービスプリンシパルとそのOAuthシークレットを作成します。「OAuthを使用したDatabricksへのサービスプリンシパル アクセスの承認」を参照してください。
- サービスプリンシパルをワークスペースに割り当て、エンドポイントで
CAN_QUERYを付与します。 - アプリケーションから、サービスプリンシパルの認証情報とエンドポイントIDを参照する
authorization_detailsを使用してPOST <workspace-host>/oidc/v1/tokenを呼び出し、エンドポイントスコープのトークンを発行します。See Fetch an OAuth token manually. - 結果のトークンを使用して、ルートが最適化されたURLを呼び出します。
上記の「クイックスタート」セクションには、すべてのステップを網羅した単一のコピー＆ペースト可能なスクリプトが含まれています。
トラブルシューティング
エラー | 原因 | 修正 |
|---|---|---|
| トークンは個人用アクセストークンまたはクラスターランタイムトークンであり、OAuth JWT ではありません。ルート最適化されたエンドポイントはOAuthトークンのみを受け入れます。 | OAuth M2Mフローを持つサービスプリンシパルを使用してOAuthトークンを取得します。「プログラムでOAuthトークンを取得する」を参照してください。 |
| トークンリクエストで、トークンを特定のエンドポイントにダウンスコープするための |
|
| リクエストは、ルート最適化された URL ではなく、ワークスペース URL |
|
| サービスプリンシパルはエンドポイントで | エンドポイントの |
| トークンリクエストは | ルート最適化されたエンドポイントのトークンでサポートされている唯一のスコープは |