Connettersi a un'app Databricks per le API usando l'autenticazione basata su token

È possibile chiamare un'app Databricks che espone un'API HTTP (ad esempio, un'app FastAPI o Gradio) utilizzando l'autenticazione tramite token Bearer OAuth 2.0. Questo metodo funziona dall'ambiente di sviluppo locale, dalle applicazioni esterne e da altre app Azure Databricks.

Annotazioni

Questo metodo si applica solo alle app che espongono API o endpoint (accessibili tramite /api/ route). Per le app che forniscono solo un'interfaccia utente o un'elaborazione in background, non è possibile connettersi usando l'autenticazione basata su token.

Requisiti

Per connettersi a un'app Databricks usando l'autenticazione basata su token, è necessario soddisfare i requisiti seguenti:

L'app deve esporre almeno un endpoint API accessibile tramite /api/ route.
È necessario disporre CAN USE dell'autorizzazione per l'applicazione. Vedere Configurare le autorizzazioni per un'app Databricks.
È necessario essere in grado di generare un token di accesso Azure Databricks usando uno dei metodi di autenticazione supportati.

Metodi di autenticazione

Annotazioni

Non è possibile chiamare un'app Databricks direttamente usando un token di Azure Entra ID. La federazione dei token richiede un passaggio di scambio di token sul lato client, che Azure Databricks non esegue il lato server. Per usare i token Azure Entra ID per l'autenticazione, è prima necessario scambiarli per i token OAuth. Consulta l'autenticazione con un token del fornitore di identità.

Scegliere il metodo di autenticazione corrispondente allo scenario di connessione:

Sviluppo locale

Per la connessione dall'ambiente di sviluppo locale, usare l'interfaccia della riga di comando di Databricks o gli SDK con le credenziali utente.

Accedi con il CLI:
```
databricks auth login --host https://<workspace-url> --profile my-env
```
Azure Databricks consiglia di usare OAuth utente-macchina (U2M).

Generare un token di accesso:

CLI

databricks auth token --profile my-env

Python

from databricks.sdk.core import Config
config = Config(profile="my-env")
token = config.oauth_token().access_token

Applicazioni esterne

Per l'accesso programmatico da applicazioni esterne, usare l'autenticazione dei principali di servizio con credenziali inter-macchina (M2M). Consulta Autorizzare l'accesso del principale del servizio ad Azure Databricks con OAuth.

Creare un principale del servizio e ottenere l'ID client e la chiave segreta. Vedi Principali del servizio.

Generare un token di accesso usando Databricks SDK:

from databricks.sdk import WorkspaceClient
import requests

# Option 1: Explicit credentials
wc = WorkspaceClient(
    host="https://<workspace-url>",
    client_id="<service-principal-client-id>",
    client_secret="<service-principal-client-secret>"
)

# Option 2: Environment variables
# Set DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
wc = WorkspaceClient()

# Generate Bearer token
headers = wc.config.authenticate()

Da altre app di Databricks

Quando ci si connette da un'app Databricks a un'altra, l'app gestisce automaticamente l'autenticazione usando l'entità servizio assegnata.

from databricks.sdk import WorkspaceClient
import requests

# No explicit credentials needed, uses app's service principal
wc = WorkspaceClient()
headers = wc.config.authenticate()

Da un notebook di Azure Databricks

Per chiamare un'API dell'app da un notebook di Azure Databricks, è necessario scambiare il token interno del notebook per un token OAuth con ambito pubblico, quindi usare tale token per eseguire query sull'app.

Ottenere l'ID client OAuth dell'app. Recuperare l'ID usando Azure Databricks SDK:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
app_client_id = w.apps.get("<app-name>").oauth2_app_client_id

Exchange il token del notebook per un token di accesso con ambito audience:

import requests

url = "https://<workspace-url>/oidc/v1/token"
notebook_token = (
    dbutils.notebook.entry_point.getDbutils()
    .notebook().getContext().apiToken().get()
)

data = {
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "subject_token": notebook_token,
    "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "all-apis",
    "audience": app_client_id,
}

response = requests.post(url=url, data=data)
audience_token = response.json()["access_token"]

Utilizzare audience_token come token Bearer per invocare l'applicazione. Per esempi, vedere Inviare richieste all'app.

Annotazioni

Il token scambiato ha come ambito l'app specifica, quindi non è possibile usarlo per chiamare altre API Azure Databricks. Il scope parametro nella richiesta di scambio di token deve corrispondere o essere un superset degli ambiti configurati per l'app nell'autorizzazione utente.

Specificare gli ambiti OAuth per l'autorizzazione utente

Se l'app usa l'autorizzazione utente, il token di accesso deve includere ambiti che sono un superset degli ambiti configurati per l'app. Se il token non ha gli ambiti necessari, le richieste possono avere esito negativo con errori 401 o 403.

Un token generato tramite l'interfaccia della riga di comando di Databricks include l'ambito all-apis per impostazione predefinita, che soddisfa i requisiti di autorizzazione utente per qualsiasi app:

databricks auth token --profile my-env

È possibile richiedere manualmente un token di accesso con scopi espliciti usando un flusso OAuth personalizzato, per richiedere scopi specifici anziché all-apis. Ad esempio, la richiesta seguente richiede esplicitamente un token di accesso con gli ambiti sql, file.files e dashboards.genie.

curl --request POST \
https://<databricks-instance>/oidc/v1/token \
--data "client_id=databricks-cli" \
--data "grant_type=authorization_code" \
--data "redirect_uri=<redirect-url>" \
--data "code_verifier=<code-verifier>" \
--data "code=<authorization-code>" \
--data "scope=sql+file.files+dashboards.genie"

Per istruzioni complete, vedere Generare manualmente token di accesso U2M OAuth.

Inviare richieste all'app

Quando chiami gli endpoint API della tua app, includi il token Bearer nell'intestazione Autorizzazione e sostituisci <your-endpoint> con il percorso API effettivo della tua app.

CURL

curl "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>" \
     -H "Authorization: Bearer <YOUR_TOKEN>"

Python con richieste

import requests

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers={"Authorization": f"Bearer {token}"}
)

Python con SDK

from databricks.sdk import WorkspaceClient
import requests

wc = WorkspaceClient()
headers = wc.config.authenticate()

response = requests.get(
    "https://<app-name>-<id>.<region>.databricksapps.com/api/<your-endpoint>",
    headers=headers
)

Considerazioni sulla sicurezza

Quando ci si connette alle app dall'ambiente locale, seguire queste procedure consigliate per la sicurezza:

Non incorporare mai i token di accesso nel codice sorgente. Usare variabili di ambiente o archivi di credenziali sicure.
Aggiornare regolarmente i token per ridurre al minimo i rischi di sicurezza in caso di compromissione.
Evitare di registrare i token di accesso o i dati sensibili nei log dell'applicazione.

Risoluzione dei problemi

Se si verificano problemi durante la connessione all'app da un computer locale, provare queste soluzioni.

Errori di autenticazione (errori 401)

Verificare quanto segue:

Il token è valido (eseguire databricks auth token --profile my-env)
Il profilo è configurato correttamente con databricks auth login
Il token non è scaduto
Il token include gli ambiti OAuth necessari. Gli ambiti del token devono essere un superset degli ambiti configurati per l'app nell'autorizzazione utente.

Autorizzazione negata (errori 403)

Verificare quanto segue:

Hai CAN USE il permesso per l'app
Il token include gli ambiti OAuth necessari. Gli ambiti di autorizzazione insufficienti possono causare errori 403 anche con permessi validi.

App non trovata (errori 404)

Verificare quanto segue:

L'ID e l'URL dell'area di lavoro sono corretti
L'applicazione è stata distribuita ed è in esecuzione
Il percorso dell'endpoint è presente nell'app

Problemi relativi alla connettività di rete

Verificare quanto segue:

La rete consente connessioni HTTPS in uscita
Il *.databricksapps.com dominio è accessibile dalla rete

Controllare inoltre se l'organizzazione usa un proxy che richiede la configurazione.

Risorse aggiuntive

Per altre informazioni, vedere le risorse seguenti:

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-04-11

Condividi tramite

Connettersi a un'app Databricks per le API usando l'autenticazione basata su token

Requisiti

Metodi di autenticazione

Sviluppo locale

CLI

Python

Applicazioni esterne

Da altre app di Databricks

Da un notebook di Azure Databricks

Specificare gli ambiti OAuth per l'autorizzazione utente

Inviare richieste all'app

CURL

Python con richieste

Python con SDK

Considerazioni sulla sicurezza

Risoluzione dei problemi

Errori di autenticazione (errori 401)

Autorizzazione negata (errori 403)

App non trovata (errori 404)

Problemi relativi alla connettività di rete

Risorse aggiuntive

Commenti e suggerimenti

Risorse aggiuntive