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 endpoint de modelo de abastecimento ou endpoint Feature Serving que tem a otimização de rota habilitada. Veja 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.

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

Você pode obter esse URL no seguinte:

Serving UI

REST API

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

Databricks SDK

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:

1. Na página Ponto de extremidade de serviço, selecione seu endpoint otimizado para rota para ver os detalhes endpoint .
2. Na página de detalhes do endpoint, selecione o botão Usar .
3. Selecione Fetch tokens tab.
4. 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

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"

Python

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

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

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

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"

Python

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)