Interroger les Endpoint de diffusion optimisés par route

Cet article décrit comment récupérer les informations d'identification d'authentification et l'URL appropriées afin que vous puissiez interroger votre endpoint de service de modèle ou de Feature Serving optimisé pour l'acheminement.

Exigences

Un Endpoint de service de modèle ou un Endpoint de Feature Serving avec optimisation d'itinéraire activée. Voir Optimisation de l'itinéraire sur les Endpoint de service.
L'interrogation des Endpoint optimisés pour l'itinéraire ne prend en charge que l'utilisation de jetons OAuth. Les jetons d'accès personnel ne sont pas pris en charge.

Quick start: recette de query de bout en bout

La recette suivante combine toutes les étapes nécessaires pour query un endpoint optimisé en fonction de l'itinéraire à partir d'un client externe en un seul flux exécutable. Utilisez cette section si vous souhaitez vérifier rapidement une configuration fonctionnelle. Voir les sections suivantes pour plus de détails sur chaque étape.

Bash
# 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"

Récupérer l'URL optimisée pour l'itinéraire

attention

À compter du 22 septembre 2025 , tous les Endpoints optimisés pour l'itinéraire nouvellement créés devront être interrogés exclusivement via l'URL optimisée pour l'itinéraire. Les Endpoints créés après cette date ne prennent pas en charge l'interrogation via l'URL du workspace.

Si votre Endpoint optimisé pour l'itinéraire a été créé avant le 22 septembre 2025 :

L'URL standard du Workspace peut également être utilisée pour interroger l'Endpoint. Le chemin d'accès standard de l'URL du Workspace n'offre pas les avantages de l'optimisation des itinéraires.

https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations
Les Endpoint optimisés pour l'itinéraire créés avant cette date continuent de prendre en charge les deux URL d'invocation : le chemin d'URL optimisé pour l'itinéraire et le chemin d'URL standard du Workspace.

Lorsque vous créez un endpoint optimisé pour l’itinéraire, l’URL optimisée pour l’itinéraire suivante est créée pour l’endpoint.

https://<unique-id>.serving.cloud.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

Vous pouvez obtenir cette URL à partir des éléments suivants :

Serving UI
REST API
Databricks SDK

URL d'Endpoint optimisé pour l'itinéraire

Utilisez l'appel de l'GET /api/2.0/serving-endpoints/{name} API. L'URL est présente dans l'objet de réponse de l'endpoint sous la forme endpoint_url. Ce champ est renseigné uniquement si l'endpoint est optimisé pour l'itinéraire.

Bash
GET /api/2.0/serving-endpoints/my-endpoint
{
  "name": "my-endpoint"
}

Utilisez l'appel Serving Endpoints API get. L'URL est présente dans l'objet de réponse de l'endpoint sous la forme endpoint_url. Ce champ est renseigné uniquement si l'endpoint est optimisé pour l'itinéraire.

Python
from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

workspace.serving_endpoints.get("my-endpoint")

Récupérez un jeton OAuth et interrogez l'Endpoint

Pour interroger votre Endpoint optimisé pour l'itinéraire, vous devez utiliser un jeton OAuth. Databricks recommande d'utiliser des Service Principal dans vos applications de production pour récupérer des jetons OAuth par programmation. Les sections suivantes décrivent les directives recommandées sur la façon de récupérer un jeton OAuth pour les scénarios de test et de production.

Récupérer un jeton OAuth à l'aide de l'interface utilisateur de Serving

Les étapes suivantes expliquent comment récupérer un jeton dans l'interface utilisateur de Serving. Ces étapes sont recommandées pour le développement et le test de votre endpoint.

Pour une utilisation en production, comme l'utilisation de votre endpoint optimisé pour l'itinéraire dans une application, votre jeton est récupéré à l'aide d'un Service Principal. Consultez Récupérer un jeton OAuth par programmation pour obtenir des conseils recommandés sur la récupération de votre jeton OAuth pour les cas d'utilisation en production.

De l' interface utilisateur de service de votre Workspace :

Sur la page Endpoints de diffusion, sélectionnez votre endpoint optimisé pour l'itinéraire pour afficher les détails du endpoint.
Sur la page des détails de l'Endpoint, sélectionnez le bouton **Utiliser**.
Sélectionnez l'onglet Fetch Token tab.
Cliquez sur le bouton Récupérer le jeton OAuth . Ce jeton est valide pendant 1 heure. Récupérez un nouveau jeton si votre jeton actuel expire.

Après avoir récupéré le jeton OAuth, query votre Endpoint en utilisant votre URL d'Endpoint et votre jeton OAuth.

REST API
Python

Voici un exemple d'API REST :

Bash

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

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

Voici un exemple 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)

Récupérer un jeton OAuth par programmation

Pour les scénarios de production, Databricks recommande de configurer des Service Principal à intégrer dans votre application pour récupérer programmatiquement les jetons OAuth. Ces jetons récupérés sont utilisés pour interroger les Endpoint optimisés pour l’itinéraire.

Suivez les étapes de la section Autoriser l'accès du Service Principal à Databricks avec OAuth jusqu'à l'étape 2 pour créer votre Service Principal, attribuer des autorisations et créer un secret OAuth pour votre Service Principal. Une fois votre Service Principal créé, vous devez donner au Service Principal au moins l' autorisation de Query sur l'Endpoint. Consultez Gérer les autorisations sur un Endpoint de mise en service de modèle.

Le SDK Python Databricks fournit une API pour interroger directement un Endpoint optimisé pour l'itinéraire.

remarque

Le Databricks SDK est également disponible en Go, voir Databricks SDK for Go.

L'exemple suivant nécessite ce qui suit pour interroger un endpoint optimisé par itinéraire à l'aide du SDK Databricks :

Nom de l'endpoint de service (le SDK récupère l'URL d'endpoint correcte basée sur ce nom)
ID client du Service Principal
Secret de Service Principal
Hostname du Workspace

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 = ....)

Récupérez manuellement un jeton OAuth

Pour les scénarios où le SDK Databricks ou l'interface utilisateur de Serving ne peuvent pas être utilisés pour récupérer votre jeton OAuth, vous pouvez récupérer manuellement un jeton OAuth. Les conseils de cette section s'appliquent principalement aux scénarios où les utilisateurs disposent d'un client personnalisé qu'ils souhaitent utiliser pour interroger l'endpoint en production.

Lorsque vous récupérez manuellement un jeton OAuth, vous devez spécifier authorization_details dans la requête.

Construisez le <token-endpoint-URL> en remplaçant https://<databricks-instance> par l'URL du workspace de votre déploiement Databricks dans https://<databricks-instance>/oidc/v1/token. Par exemple, https://my-workspace.cloud.databricks.com/oidc/v1/token
Remplacez <client-id> par l'ID client du Service Principal, également connu sous le nom d'ID d'application.
Remplacez <client-secret> par le secret OAuth du Service Principal que vous avez créé.
Remplacez <endpoint-id> par l'ID d'Endpoint de l'Endpoint optimisé pour l'itinéraire. Il s'agit de l'ID alphanumérique de l'Endpoint que vous pouvez trouver dans le hostName de l'URL de l'Endpoint. Par exemple, si l'Endpoint de service est https://abcdefg.serving.cloud.databricks.com/9999999/serving-endpoints/test, l'ID de l'Endpoint est abcdefg.
Remplacez <action> par l’autorisation d'action accordée au Service Principal. L’action peut être query_inference_endpoint ou manage_inference_endpoint.

REST API
Python

Voici un exemple d'API REST :

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"'"]}]'

Voici un exemple 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}")

Après avoir récupéré le jeton OAuth, query votre Endpoint en utilisant votre URL d'Endpoint et votre jeton OAuth.

REST API
Python

Voici un exemple d'API REST :

Bash

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

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

Voici un exemple 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)

Appel depuis un agent d'IA ou une application externe

Les assistants de code IA et les applications externes qui interrogent les Endpoint optimisés pour l'itinéraire ne peuvent pas utiliser le jeton d'accès personnel d'un développeur ou les jetons OAuth du Workspace. Ils doivent utiliser un Service Principal avec le flux M2M OAuth et inclure authorization_details dans la demande de jeton. Le flux est :

Créez un service principal au niveau du compte et un secret OAuth pour celui-ci. Consultez Autoriser l'accès de service principal à Databricks avec OAuth.
Attribuez le Service Principal au Workspace et accordez-lui CAN_QUERY sur l'Endpoint.
À partir de l'application, créez un jeton délimité par l'endpoint en appelant POST <workspace-host>/oidc/v1/token avec les informations d'identification du Service Principal et authorization_details en référençant l'ID d'endpoint. Consultez Récupérer manuellement un jeton OAuth.
Invoquez l'URL optimisée pour l'itinéraire avec le Jeton résultant.

La section Quick start ci-dessus contient un script unique que vous pouvez copier-coller qui couvre chaque étape.

Dépannage

Erreur	Cause	Corriger
`401 Malformed token` retourné par l'URL optimisée pour l'itinéraire	Le jeton est un jeton d'accès personnel ou un jeton d'exécution de cluster plutôt qu'un JWT OAuth. Les endpoints optimisés pour l'itinéraire n'acceptent que les jetons OAuth.	Utilisez un Service Principal avec le flux OAuth M2M pour récupérer un jeton OAuth. Consultez Récupérer un jeton OAuth par programmation.
`401 Missing authorization details for accessing model serving endpoints` retourné par l'URL optimisée pour l'itinéraire	La requête de jeton a omis la revendication `authorization_details` qui réduit la portée du jeton à l'Endpoint spécifique. Un jeton `scope=all-apis` simple n'est pas suffisant.	Passez `authorization_details` en référençant l'ID de l'Endpoint et l'action `query_inference_endpoint` lors de l'appel à `/oidc/v1/token`. Consulter Récupérer un jeton OAuth manuellement.
`400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ...`	Vous avez envoyé la demande à l'URL du Workspace `https://<workspace>/serving-endpoints/<name>/invocations` au lieu de l'URL optimisée pour l'itinéraire.	Utilisez l’URL renvoyée dans le champ `endpoint_url` de `GET /api/2.0/serving-endpoints/<name>`. Voir Récupérer l'URL optimisée par l'itinéraire.
`403 Permission denied` renvoyé par l'URL optimisée pour l'itinéraire même si le jeton OAuth a `authorization_details`	Le Service Principal ne dispose pas de `CAN_QUERY` sur l'Endpoint, ou l'action dans `authorization_details` ne correspond pas à l'autorisation accordée.	Accorder `CAN_QUERY` sur l'endpoint au Service Principal et utiliser `query_inference_endpoint` comme action. Voir Gérer les autorisations sur un endpoint de service de modèle.
`invalid_scope` renvoyé de `/oidc/v1/token`	La demande de jeton a transmis une valeur de périmètre autre que `all-apis`.	La seule portée prise en charge pour les jetons Endpoint optimisés pour les routes est `all-apis`. La portée réduite de l'Endpoint se fait via `authorization_details`, et non `scope`.

Erreur	Cause	Corriger
`401 Malformed token` retourné par l'URL optimisée pour l'itinéraire	Le jeton est un jeton d'accès personnel ou un jeton d'exécution de cluster plutôt qu'un JWT OAuth. Les endpoints optimisés pour l'itinéraire n'acceptent que les jetons OAuth.	Utilisez un Service Principal avec le flux OAuth M2M pour récupérer un jeton OAuth. Consultez Récupérer un jeton OAuth par programmation.
`401 Missing authorization details for accessing model serving endpoints` retourné par l'URL optimisée pour l'itinéraire	La requête de jeton a omis la revendication `authorization_details` qui réduit la portée du jeton à l'Endpoint spécifique. Un jeton `scope=all-apis` simple n'est pas suffisant.	Passez `authorization_details` en référençant l'ID de l'Endpoint et l'action `query_inference_endpoint` lors de l'appel à `/oidc/v1/token`. Consulter Récupérer un jeton OAuth manuellement.
`400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ...`	Vous avez envoyé la demande à l'URL du Workspace `https://<workspace>/serving-endpoints/<name>/invocations` au lieu de l'URL optimisée pour l'itinéraire.	Utilisez l’URL renvoyée dans le champ `endpoint_url` de `GET /api/2.0/serving-endpoints/<name>`. Voir Récupérer l'URL optimisée par l'itinéraire.
`403 Permission denied` renvoyé par l'URL optimisée pour l'itinéraire même si le jeton OAuth a `authorization_details`	Le Service Principal ne dispose pas de `CAN_QUERY` sur l'Endpoint, ou l'action dans `authorization_details` ne correspond pas à l'autorisation accordée.	Accorder `CAN_QUERY` sur l'endpoint au Service Principal et utiliser `query_inference_endpoint` comme action. Voir Gérer les autorisations sur un endpoint de service de modèle.
`invalid_scope` renvoyé de `/oidc/v1/token`	La demande de jeton a transmis une valeur de périmètre autre que `all-apis`.	La seule portée prise en charge pour les jetons Endpoint optimisés pour les routes est `all-apis`. La portée réduite de l'Endpoint se fait via `authorization_details`, et non `scope`.

Exigences​

Quick start: recette de query de bout en bout​

Récupérer l'URL optimisée pour l'itinéraire​

Récupérez un jeton OAuth et interrogez l'Endpoint​

Récupérer un jeton OAuth à l'aide de l'interface utilisateur de Serving​

Récupérer un jeton OAuth par programmation​

Récupérez manuellement un jeton OAuth​

Appel depuis un agent d'IA ou une application externe​

Dépannage​

Exigences

Quick start: recette de query de bout en bout

Récupérer l'URL optimisée pour l'itinéraire

Récupérez un jeton OAuth et interrogez l'Endpoint

Récupérer un jeton OAuth à l'aide de l'interface utilisateur de Serving

Récupérer un jeton OAuth par programmation

Récupérez manuellement un jeton OAuth

Appel depuis un agent d'IA ou une application externe

Dépannage