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 endpoint do modelo de serviço otimizado para rota.

Requisitos

Um modelo de serviço endpoint que tenha a otimização de rota ativada, consulte Otimização de rota no ponto de extremidade de serviço.
A consulta de endpoint otimizado para rota suporta apenas o uso tokens OAuth . access tokens pessoal não são suportados.

Início rápido: receita de consulta de ponta a ponta

A receita a seguir combina cada passo necessário para consultar um endpoint otimizado para rotas a partir de um cliente externo em um único fluxo executável. Use esta seção se você quiser verificar uma configuração funcional rapidamente. Consulte as seções a seguir para mais detalhes sobre cada passo.

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"

Obter o URL otimizado para rotas

atenção

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. endpoints criados após esta data não suportam consultas por meio da URL workspace .

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 e 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.gcp.databricks.com/<workspace-id>/serving-endpoints/<endpoint-name>/invocations

Você pode obter esse URL no seguinte:

Serving UI
REST API
Databricks SDK

URL endpoint otimizado para rota

Use a chamada de API GET /api/2.0/serving-endpoints/{name} . A URL está presente no objeto de resposta do endpoint como endpoint_url. Este campo só será preenchido se o endpoint for otimizado para rota.

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

Use a chamada Serving Endpoints API get . A URL está presente no objeto de resposta do endpoint como endpoint_url. Este campo só será preenchido se o endpoint for otimizado para rota.

Python
from databricks.sdk import WorkspaceClient

workspace = WorkspaceClient()

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

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:

Bash

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:

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 Autorizar o acesso da entidade de serviço ao Databricks com OAuth através do passo 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, você deverá conceder à entidade de serviço pelo menos permissão de consulta no endpoint. Consulte gerenciamento de permissões em um modelo endpointinstalado.

O Databricks Python SDK fornece uma API para consultar diretamente um endpoint otimizado para rota.

nota

O SDK da Databricks também está disponível em Go, consulte SDK da Databricks para Go.

O próximo 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

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

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> substituindo https://<databricks-instance> pelo URL workspace da sua implantação Databricks em https://<databricks-instance>/oidc/v1/token. Por exemplo, https://my-workspace.gcp.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 no hostName do URL do endpoint . Por exemplo, se o endpoint de serviço for https://abcdefg.serving.gcp.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 ser query_inference_endpoint ou manage_inference_endpoint.

REST API
Python

A seguir, um exemplo de 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"'"]}]'

A seguir, um exemplo em 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}")

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:

Bash

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:

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)

Chamando de um agente de IA ou aplicativo externo

Assistentes de codificação de AI e aplicativos externos que consultam endpoints otimizados para rotas não podem usar o token de acesso pessoal de um desenvolvedor ou tokens OAuth do workspace. É necessário usar uma entidade de serviço com o fluxo OAuth M2M e incluir authorization_details na solicitação de token. O fluxo é:

Crie uma entidade de serviço no nível da conta e um segredo OAuth para ela. Consulte Autorizar o acesso de entidade de serviço ao Databricks com OAuth.
Atribua a entidade de serviço ao workspace e conceda a ela CAN_QUERY no endpoint.
Do aplicativo, crie um token com escopo de endpoint chamando POST <workspace-host>/oidc/v1/token com as credenciais da entidade de serviço e authorization_details fazendo referência à ID do endpoint. Consulte Obter um token OAuth manualmente.
Invoque o URL otimizado para rotas com o token resultante.

A seção Início rápido acima contém um único script que pode ser copiado e colado e que abrange cada etapa.

Solução de problemas

Erro	Causa	Corrigir
`401 Malformed token` retornado do URL otimizado para rotas	O token é um access token pessoal ou um token de tempo de execução de cluster, em vez de um JWT OAuth. Endpoints otimizados para rotas aceitam apenas tokens OAuth.	Use uma entidade de serviço com o fluxo OAuth M2M para buscar um token OAuth. Consulte Obter um token OAuth programaticamente.
`401 Missing authorization details for accessing model serving endpoints` retornado do URL otimizado para rotas	A solicitação de token omitiu a declaração `authorization_details` que restringe o token ao endpoint específico. Um token `scope=all-apis` simples não é suficiente.	Passe `authorization_details` referenciando o ID do endpoint e a ação `query_inference_endpoint` ao chamar `/oidc/v1/token`. Consulte Obter um token OAuth manualmente.
`400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ...`	A solicitação foi enviada para o URL do workspace `https://<workspace>/serving-endpoints/<name>/invocations` em vez do URL otimizado para rotas.	Use o URL retornado no campo `endpoint_url` de `GET /api/2.0/serving-endpoints/<name>`. Consulte Obter o URL otimizado para rotas.
`403 Permission denied` retornado do URL otimizado para rotas, mesmo que o token OAuth tenha `authorization_details`	A entidade de serviço não tem `CAN_QUERY` no endpoint, ou a ação em `authorization_details` não corresponde à permissão concedida.	Conceda `CAN_QUERY` no endpoint à entidade de serviço e use `query_inference_endpoint` como a ação. Consulte Gerenciar permissões em um endpoint de servindo modelo.
`invalid_scope` retornado de `/oidc/v1/token`	A solicitação de token incluiu um valor de escopo diferente de `all-apis`.	O único escopo compatível para tokens de endpoint otimizado para rotas é `all-apis`. A redução de escopo do endpoint acontece por meio de `authorization_details`, não `scope`.

Erro	Causa	Corrigir
`401 Malformed token` retornado do URL otimizado para rotas	O token é um access token pessoal ou um token de tempo de execução de cluster, em vez de um JWT OAuth. Endpoints otimizados para rotas aceitam apenas tokens OAuth.	Use uma entidade de serviço com o fluxo OAuth M2M para buscar um token OAuth. Consulte Obter um token OAuth programaticamente.
`401 Missing authorization details for accessing model serving endpoints` retornado do URL otimizado para rotas	A solicitação de token omitiu a declaração `authorization_details` que restringe o token ao endpoint específico. Um token `scope=all-apis` simples não é suficiente.	Passe `authorization_details` referenciando o ID do endpoint e a ação `query_inference_endpoint` ao chamar `/oidc/v1/token`. Consulte Obter um token OAuth manualmente.
`400 This is a route-optimized endpoint. Please use the correct route-optimized URL provided: ...`	A solicitação foi enviada para o URL do workspace `https://<workspace>/serving-endpoints/<name>/invocations` em vez do URL otimizado para rotas.	Use o URL retornado no campo `endpoint_url` de `GET /api/2.0/serving-endpoints/<name>`. Consulte Obter o URL otimizado para rotas.
`403 Permission denied` retornado do URL otimizado para rotas, mesmo que o token OAuth tenha `authorization_details`	A entidade de serviço não tem `CAN_QUERY` no endpoint, ou a ação em `authorization_details` não corresponde à permissão concedida.	Conceda `CAN_QUERY` no endpoint à entidade de serviço e use `query_inference_endpoint` como a ação. Consulte Gerenciar permissões em um endpoint de servindo modelo.
`invalid_scope` retornado de `/oidc/v1/token`	A solicitação de token incluiu um valor de escopo diferente de `all-apis`.	O único escopo compatível para tokens de endpoint otimizado para rotas é `all-apis`. A redução de escopo do endpoint acontece por meio de `authorization_details`, não `scope`.

Requisitos​

Início rápido: receita de consulta de ponta a ponta​

Obter o URL otimizado para rotas​

Obtenha um OAuth tokens e consulte o endpoint​

Obtenha tokens OAuth usando a UI de serviço​

Obter um OAuth tokens programaticamente​

Obter um OAuth tokens manualmente​

Chamando de um agente de IA ou aplicativo externo​

Solução de problemas​

Requisitos

Início rápido: receita de consulta de ponta a ponta

Obter o URL otimizado para rotas

Obtenha um OAuth tokens e consulte o endpoint

Obtenha tokens OAuth usando a UI de serviço

Obter um OAuth tokens programaticamente

Obter um OAuth tokens manualmente

Chamando de um agente de IA ou aplicativo externo

Solução de problemas