Ponto de extremidade de serviço otimizado para rota de consulta
Este artigo descreve como obter as credenciais de autenticação e a URL apropriadas para que você possa consultar seu modelo de serviço otimizado para rota ou endpoint Feature Serving .
Requisitos
- Um modelo de serviço endpoint ou Feature Serving endpoint que tenha a otimização de rota ativada, consulte Otimização de rota no endpoint de serviço.
- Tokens de autenticação. O ponto de extremidade com otimização de rota suporta apenas OAuth tokens, o acesso pessoal tokens não é suportado.
Obter a URL otimizada para rota
A partir de 22 de setembro de 2025 , todos os endpoints otimizados para rota recém-criados devem ser consultados exclusivamente por meio do URL otimizado para rota. Após essa data, a URL workspace não será mais suportada para esses novos endpoints.
Se o seu endpoint otimizado para rota foi criado antes de 22 de setembro de 2025 :
-
O URL padrão workspace também pode ser usado para consultar o endpoint. O caminho de URL workspace padrão não fornece os benefícios da otimização de rota.
https://<databricks-workspace>/serving-endpoints/<endpoint-name>/invocations
-
O ponto de extremidade otimizado para rota criado antes desta data continua a oferecer suporte a ambos os URLs de invocação: o caminho de URL otimizado para rota ou o caminho de URL workspace padrão.
Quando você cria um endpoint otimizado para rota, o seguinte URL otimizado para rota é criado para o endpoint.
https://<unique-id>.serving.cloud.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations
Você pode obter esse URL de uma das seguintes opções:
-
Usando a chamada de API
GET /api/2.0/serving-endpoints/{name}
. A URL está presente no objeto de resposta do endpoint comoendpoint_url
. Este campo só será preenchido se o endpoint for otimizado para rota. -
A página de detalhes do endpoint de atendimento na interface de usuário de atendimento.
Obtenha um OAuth tokens e consulte o endpoint
Para consultar seu endpoint otimizado para rota, você deve usar tokens OAuth . Databricks recomenda usar a entidade de serviço em seus aplicativos de produção para buscar tokens OAuth programaticamente. As seções a seguir descrevem orientações recomendadas sobre como obter tokens OAuth para cenários de teste e produção.
Obtenha tokens OAuth usando a UI de serviço
As etapas a seguir mostram como buscar tokens na UI de serviço. Essas etapas são recomendadas para desenvolver e testar seu endpoint.
Para uso em produção, como usar seu endpoint otimizado para rota em um aplicativo, seus tokens são obtidos usando uma entidade de serviço. Consulte Obter tokens OAuth programaticamente para obter orientações recomendadas sobre como buscar seus tokens OAuth para casos de uso de produção.
Na interface de usuário de serviço do site workspace:
- Na página Ponto de extremidade de serviço, selecione seu endpoint otimizado para rota para ver os detalhes endpoint .
- Na página de detalhes do endpoint, selecione o botão Usar .
- Selecione Fetch tokens tab.
- Selecione o botão Fetch OAuth tokens . Esses tokens são válidos por 1 hora. Obtenha novos tokens se os tokens atuais expirarem.
Depois de obter os tokens OAuth, consulte o site endpoint usando o URL endpoint e os tokens OAuth.
- REST API
- Python
A seguir, um exemplo de API REST:
URL="<endpoint-url>"
OAUTH_TOKEN="<token>"
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OAUTH_TOKEN" \
--data "@data.json" \
"$URL"
A seguir, um exemplo em 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)
Obter um OAuth tokens programaticamente
Para cenários de produção, Databricks recomenda configurar uma entidade de serviço para incorporar ao seu aplicativo para buscar tokens OAuth programaticamente. Esses tokens buscados são usados para consultar o ponto de extremidade otimizado para rota.
Siga as etapas em Authorize entidade de serviço access to Databricks with OAuth até a etapa 2 para criar sua entidade de serviço, atribuir permissões e criar um segredo OAuth para sua entidade de serviço. Depois que sua entidade de serviço for criada, o senhor deve conceder à entidade de serviço pelo menos a permissão de consulta no site endpoint. Consulte gerenciar permissões em seu modelo de serviço endpoint.
O Databricks Python SDK fornece uma API para consultar diretamente um endpoint otimizado para rota.
O SDK da Databricks também está disponível em Go, consulte SDK da Databricks para Go.
O exemplo requer o seguinte para consultar um endpoint otimizado para rota usando o Databricks SDK:
- Nome do endpoint de serviço (o SDK busca o URL correto do endpoint com base nesse nome)
- ID do cliente principal do serviço
- Segredo principal do serviço
- nome do host do espaço de trabalho
Veja a seguir um exemplo de consulta:
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 = ....)
Obter um OAuth tokens manualmente
Em cenários em que o Databricks SDK ou a Serving UI não podem ser usados para obter os tokens OAuth, o senhor pode obter manualmente os tokens OAuth. As orientações desta seção se aplicam principalmente a cenários em que os usuários têm um cliente personalizado que desejam usar para consultar o endpoint na produção.
Quando o senhor busca manualmente os tokens OAuth, deve especificar authorization_details
na solicitação.
-
Construa o
<token-endpoint-URL>
substituindohttps://<databricks-instance>
pelo URL workspace da sua implantação Databricks emhttps://<databricks-instance>/oidc/v1/token
. Por exemplo,https://my-workspace.cloud.databricks.com/oidc/v1/token
-
Substitua
<client-id>
pela ID do cliente da entidade de serviço, que também é conhecida como ID do aplicativo. -
Substitua
<client-secret>
pelo segredo OAuth da entidade de serviço que o senhor criou. -
Substitua
<endpoint-id>
pelo ID do endpoint do endpoint otimizado para rota. Este é o ID alfanumérico do endpoint que você pode encontrar nohostName
do URL do endpoint . Por exemplo, se o endpoint de serviço forhttps://abcdefg.serving.cloud.databricks.com/9999999/serving-endpoints/test
, o ID endpoint seráabcdefg
. -
Substitua
<action>
pela permissão de ação dada à entidade de serviço. A ação pode serquery_inference_endpoint
oumanage_inference_endpoint
.
- REST API
- Python
A seguir, um exemplo de API REST:
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"'"]}]'
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}")
Depois de obter os tokens OAuth, consulte o site endpoint usando o URL endpoint e os tokens OAuth.
- REST API
- Python
A seguir, um exemplo de API REST:
URL="<endpoint-url>"
OAUTH_TOKEN="<token>"
curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $OAUTH_TOKEN" \
--data "@data.json" \
"$URL"
A seguir, um exemplo em 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)