ルート最適化されたサービスエンドポイントをクエリする

この記事では、ルート最適化モデルサービングエンドポイントをクエリできるように、適切な認証資格情報と URL を取得する方法について説明します。

必要条件

• ルート最適化が有効になっているモデルサービングエンドポイントについては、「 サービスエンドポイントでのルート最適化」を参照してください。
• 認証トークン。ルート最適化エンドポイントは OAuth トークンのみをサポートし、パーソナル アクセス トークンはサポートされていません。

ルート最適化された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 は、次のいずれかから取得できます。

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

• Serving UI の Serving エンドポイントの詳細ページ。

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

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

Serving UI を使用した OAuth トークンの取得

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

アプリケーションでルート最適化エンドポイントを使用する場合など、本番運用で使用する場合は、サービス プリンシパルを使用して Windows が取得されます。 本番運用のユースケースでOAuthウイルスを取得するための推奨ガイダンスについては、「プログラムでOAuthウイルスを取得する」を参照してください。

ワークスペースの Serving UI から:

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

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

REST API

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

Bash

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 の例を示します。

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セキュリティを取得することをお勧めします。 取得されたトークンは、ルート最適化されたエンドポイントを照会するために使用されます。

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

Databricks Python SDK は、ルート最適化されたエンドポイントを直接クエリするための API を提供します。

注記

Databricks SDK は Go でも使用できます ( 「Databricks SDK for Go」を参照)。

この例では、Databricks SDK を使用してルート最適化エンドポイントをクエリするために以下が必要です。

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

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

Python

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

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

Bash

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

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 の例を示します。

Bash

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 の例を示します。

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)