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

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. 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 como endpoint_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.

URL endpoint otimizado para rota

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

nota

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:

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.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 no hostName do URL do endpoint . Por exemplo, se o endpoint de serviço for https://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 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"'"]}]'

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)

Requisitos​

Obter a URL otimizada para rota​

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​

Requisitos

Obter a URL otimizada para rota

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