Connettersi a servizi HTTP esterni

Importante

Questa funzionalità è in Anteprima Pubblica.

Questa pagina descrive come configurare Lakehouse Federation per eseguire query federate su dati del servizio esterni non gestiti da Azure Databricks. Per altre informazioni sulla federazione lakehouse, vedere Che cos'è Lakehouse Federation?

Per connettersi al database del servizio esterno tramite Lakehouse Federation, è necessario creare quanto segue nel metastore del catalogo Unity di Azure Databricks:

Connessione al database del servizio esterno.
Catalogo esterno che rispecchia il database del servizio esterno in Unity Catalog in modo da poter usare la sintassi delle query di Unity Catalog e gli strumenti di governance dei dati per gestire l'accesso utente di Azure Databricks al database.

Prima di iniziare

Requisiti dell'area di lavoro:

Area di lavoro attivata per il catalogo Unity.

Requisiti di calcolo:

Connettività di rete dalla risorsa di calcolo ai sistemi di database di destinazione. Vedi Raccomandazioni sulla rete per Lakehouse Federation.
Il calcolo di Azure Databricks deve usare Databricks Runtime 15.4 LTS o versione successiva e la modalità di accesso Standard o Dedicato .
I warehouse SQL devono essere pro o serverless e devono utilizzare la versione 2023.40 o successiva.

Autorizzazioni necessarie:

Per creare una connessione, è necessario essere amministratore del metastore o un utente con il privilegio CREATE CONNECTION nel metastore Unity Catalog collegato all'area di lavoro.
Per creare un catalogo straniero, è necessario avere il permesso CREATE CATALOG sul metastore ed essere il proprietario della connessione o avere il privilegio CREATE FOREIGN CATALOG sulla connessione.

In ogni sezione basata su attività che segue vengono specificati requisiti di autorizzazione aggiuntivi.

Configurare l'autenticazione per il servizio esterno usando uno dei metodi seguenti:
- Token Bearer: ottenere un token Bearer per un'autenticazione semplice basata su token.
- OAuth 2.0 Da computer a computer: creare e configurare un'app per abilitare l'autenticazione da computer a computer.
- OAuth 2.0 Condivisione tra utente e macchina: Autenticarsi con l'interazione dell'utente per condividere l'accesso tra identità del servizio e macchina.
- OAuth 2.0 User-to-Machine Per User: Autenticazione con interazione per utente per accedere tra l'identità dell'utente e la macchina.

Metodi di autenticazione per i servizi esterni

token portatore: un token portatore è un semplice meccanismo di autenticazione basato su token in cui un token viene rilasciato a un client e usato per accedere alle risorse senza richiedere credenziali aggiuntive. Il token è incluso nell'intestazione della richiesta e concede l'accesso purché sia valido.

OAuth Machine-to-Machine: L'autenticazione OAuth Machine-to-Machine (M2M) viene usata quando due sistemi o applicazioni comunicano senza coinvolgimento diretto dell'utente. I token vengono rilasciati a un client di computer registrato, che usa le proprie credenziali per l'autenticazione. Questa opzione è ideale per le attività di comunicazione da server a server, microservizi e automazione in cui non è necessario alcun contesto utente. Databricks consiglia di usare OAuth Machine-to-Machine quando è disponibile anziché OAuth User-to-Machine Condiviso.

OAuth User-to-Machine Shared:OAuth User-to-Machine Shared: L'autenticazione da utente a computer OAuth consente a una singola identità utente di autenticare e condividere lo stesso set di credenziali tra più client o utenti. Tutti gli utenti condividono lo stesso token di accesso. Questo approccio è adatto per dispositivi o ambienti condivisi in cui un'identità utente coerente è sufficiente, ma riduce la responsabilità e il rilevamento dei singoli utenti. Nei casi in cui è necessario il login di identità, selezionare Condivisione utente-macchina. Databricks consiglia di usare OAuth Machine-to-Machine quando è disponibile anziché OAuth User-to-Machine Condiviso.

Dal utente alla macchina OAuth per utente: L'autenticazione OAuth dal utente alla macchina per utente consente a ogni identità utente di autenticarsi e utilizzare le proprie credenziali per accedere alle risorse. Ogni utente viene emesso un token di accesso univoco, consentendo il controllo di accesso individuale, il controllo e la responsabilità. Questo metodo è adatto quando è necessario l'accesso ai dati specifico dell'utente e quando si accede a servizi esterni per conto dell'utente singolo.

I servizi esterni devono essere conformi alle specifiche OAuth 2.0

Le connessioni HTTP che usano OAuth devono connettersi ai servizi conformi alla specifica ufficiale di OAuth 2.0 per il modo in cui gestiscono e restituiscono i dati del token di accesso. Ciò significa che le risposte del servizio devono usare i nomi di campo e i formati di dati esatti descritti nella specifica, ad esempio access_token, expires_ine così via.

Se si verificano problemi di connessione a un servizio esterno tramite OAuth 2.0, verificare che le risposte del servizio seguano questi requisiti.

Creare una connessione al servizio esterno

Creare prima di tutto una connessione del catalogo Unity al servizio esterno che specifica un percorso e le credenziali per accedere al servizio.

I vantaggi dell'uso di una connessione al catalogo Unity includono quanto segue:

la gestione sicura delle credenziali: segreti e token vengono archiviati e gestiti in modo sicuro nel catalogo unity, assicurandosi che non siano mai esposti agli utenti.
controllo di accesso granulare: Catalogo unity consente un controllo granulare su chi può usare o gestire le connessioni con i privilegi di USE CONNECTION e MANAGE CONNECTION.
applicazione di token specifici per host: i token sono limitati agli host_name specificati durante la creazione della connessione, assicurandosi che non possano essere usati con host non autorizzati.

Autorizzazioni necessarie: Amministratore o utente Metastore con il privilegio CREATE CONNECTION.

Creare una connessione usando uno dei metodi seguenti:

Usare l'interfaccia utente dell'Esplora Catalogo.
Eseguire il comando SQL CREATE CONNECTION in un notebook di Azure Databricks o nell'editor di query SQL di Databricks.
Usare l'API REST di Databricks o l'interfaccia della riga di comando di Databricks per creare una connessione. Vedere POST /api/2.1/unity-catalog/connections e i comandi del Unity Catalog.

Esploratore di cataloghi

Usare l'interfaccia utente di Esplora cataloghi per creare una connessione.

Nell'area di lavoro di Azure Databricks fare clic Catalogo.
Nella parte superiore del riquadro Catalogo, fare clic sull'icona icona Aggiungi e selezionare Aggiungi una connessione dal menu.

In alternativa, nella pagina Accesso rapido fare clic sul pulsante Dati esterni >, passare alla scheda Connessioni e fare clic su Crea connessione.
Fai clic su Crea connessione.
Immettere un nome di connessione semplice.
Selezionare un Tipo di connessione di HTTP.
Selezionare un tipo di autenticazione tra le opzioni seguenti:
- Token di connessione
- OAuth da macchina a macchina
- Utente OAuth per Macchina Condivisa
- Utente OAuth per computer per utente

Nella pagina Autenticazione immettere le proprietà di connessione seguenti per la connessione HTTP.

Per un token portatore:

Proprietà	Descrizione	Valore di esempio
Presentatore	URL di base dell'area di lavoro o della distribuzione di Databricks.	`https://databricks.com`
Porto	La porta di rete utilizzata per la connessione è tipicamente `443` per HTTPS.	`443`
Token di connessione	Token di autenticazione usato per autorizzare le richieste API.	`bearer-token`
Percorso di base	Percorso radice per gli endpoint dell'API.	`/api/`

Per il token da computer a computer OAuth:

Proprietà	Descrizione
Client ID	Identificatore univoco per l'applicazione creata.
Segreto del cliente	Segreto o password generata per l'applicazione creata.
Ambito OAuth	Ambito di applicazione da concedere durante l'autorizzazione dell'utente. Il parametro scope è espresso come un elenco di stringhe sensibili al maiuscolo/minuscolo delimitate da spazi. Ad esempio: `channels:read channels:history chat:write`
Endpoint del token	Usato dal client per ottenere un token di accesso presentandone la concessione di autorizzazione o il token di aggiornamento. In genere nel formato: `https://authorization-server.com/oauth/token`

Per il token condiviso da utente a computer OAuth:

Verrà richiesto di accedere usando le credenziali OAuth. Le credenziali usate verranno condivise da chiunque usi questa connessione. Alcuni provider richiedono una allowlist per l'URL di reindirizzamento, includere <databricks_workspace_url>/login/oauth/http.html come allowlist per l'URL di reindirizzamento. Esempio: https://databricks.com/login/oauth/http.html

Proprietà	Descrizione
Client ID	Identificatore univoco per l'applicazione creata.
Segreto del cliente	Segreto o password generata per l'applicazione creata.
Ambito OAuth	Ambito di applicazione da concedere durante l'autorizzazione dell'utente. Il parametro scope è espresso come un elenco di stringhe sensibili al maiuscolo/minuscolo delimitate da spazi. Ad esempio: `channels:read channels:history chat:write`
Endpoint di autorizzazione	Usato per eseguire l'autenticazione con il proprietario della risorsa tramite il reindirizzamento dell'agente utente. In genere nel formato: `https://authorization-server.com/oauth/authorize`
Endpoint del token	Usato dal client per ottenere un token di accesso presentandone la concessione di autorizzazione o il token di aggiornamento. In genere nel formato: `https://authorization-server.com/oauth/token`

Per token utente OAuth da utente a macchina per utente:

A ogni utente verrà richiesto di accedere usando le proprie credenziali OAuth la prima volta che usano la connessione HTTP. Alcuni provider richiedono una allowlist per l'URL di reindirizzamento, includere <databricks_workspace_url>/login/oauth/http.html come allowlist per l'URL di reindirizzamento. Esempio: https://databricks.com/login/oauth/http.html

Proprietà	Descrizione
Client ID	Identificatore univoco per l'applicazione creata. Usato dal server di autorizzazione per identificare l'applicazione client durante il flusso OAuth.
Segreto del cliente	Segreto o password generata per l'applicazione creata. Viene usato per autenticare l'applicazione client durante lo scambio di codici di autorizzazione per i token e deve essere mantenuto riservato.
Ambito OAuth	Ambito di applicazione da concedere durante l'autorizzazione dell'utente. Espresso come elenco di stringhe con distinzione tra maiuscole e minuscole delimitate da spazi che definiscono le autorizzazioni richieste dall'applicazione. Ad esempio: `channels:read channels:history chat:write`
Endpoint di autorizzazione	Endpoint utilizzato per autenticare il proprietario della risorsa mediante il reindirizzamento dell'user-agent e ottenere l'autorizzazione. In genere nel formato: `https://authorization-server.com/oauth/authorize` Il client indirizza l'utente a questo endpoint per accedere e fornire il consenso alle autorizzazioni.
Endpoint del token	Endpoint usato dal client per scambiare una concessione di autorizzazione (ad esempio un codice di autorizzazione) o un token di aggiornamento per un token di accesso. In genere nel formato: `https://authorization-server.com/oauth/token`
Metodo di scambio delle credenziali Oauth	I provider richiedono metodi diversi per passare le credenziali client OAuth durante lo scambio di token. Selezionare una delle opzioni seguenti: header_and_body: inserisce le credenziali sia nell'intestazione dell'autorizzazione che nel corpo della richiesta (impostazione predefinita). body_only: inserisce le credenziali solo nel corpo della richiesta senza un'intestazione di autorizzazione. header_only: inserisce le credenziali solo nell'intestazione di autorizzazione (per provider come OKTA).

Fai clic su Crea connessione.

SQL

Usare il comando SQL CREATE CONNECTION per creare una connessione.

Annotazioni

Non è possibile usare il comando SQL per creare una connessione che usa OAuth Machine-to-User Shared. Segui invece le istruzioni dell'interfaccia utente di Esplora Cataloghi.

Per creare una nuova connessione usando un token Bearer , eseguire il comando seguente in un notebook o nell'editor di query SQL di Databricks.

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token '<bearer-token>'
);

Databricks consiglia di usare segreti anziché stringhe di testo non crittografato per valori sensibili come le credenziali. Per esempio:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  bearer_token secret ('<secret-scope>','<secret-key-password>')
)

Per creare una nuova connessione usando OAuth da macchina a macchina, eseguire il comando seguente in un notebook o nell'editor di query SQL di Databricks:

CREATE CONNECTION <connection-name> TYPE HTTP
OPTIONS (
  host '<hostname>',
  port '<port>',
  base_path '<base-path>',
  client_id '<client-id>'
  client_secret '<client-secret>'
  oauth_scope '<oauth-scope1> <oauth-scope-2>'
  token_endpoint '<token-endpoint>'
)

Concedere i USE CONNECTION privilegi agli enti di identità che devono usare la connessione.

Nell'area di lavoro, vai a Catalogo>Connessioni>>Autorizzazioni di connessione.
Concedere alle identità l'accesso appropriato alla connessione al catalogo Unity.

Inviare una richiesta HTTP al sistema esterno

Ora che si dispone di una connessione, scopri come inviare richieste HTTP al servizio con la funzione SQL predefinita http_request.

Autorizzazioni necessarie:USE CONNECTION sull'oggetto connessione.

Eseguire il comando SQL seguente in un notebook o nell'editor SQL di Databricks. Sostituisci i valori segnaposto:

connection-name: l'oggetto di connessione che specifica l'host, la porta, base_path e le credenziali di accesso.
http-method: metodo di richiesta HTTP usato per effettuare la chiamata. Ad esempio: GET, POST, PUT, DELETE
path: percorso da concatenare dopo il base_path per richiamare la risorsa del servizio.
json: corpo JSON da inviare con la richiesta.
headers: Una mappa per specificare le intestazioni della richiesta.

SELECT http_request(
  conn => <connection-name>,
  method => <http-method>,
  path => <path>,
  json => to_json(named_struct(
    'text', text
  )),
  headers => map(
    'Accept', "application/vnd.github+json"
  )
);

Annotazioni

L'accesso SQL con http_request è bloccato per il tipo di connessione Utente-Macchina per singolo utente. Usare invece Python Databricks SDK.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import ExternalFunctionRequestHttpMethod

WorkspaceClient().serving_endpoints.http_request(
  conn="connection-name",
  method=ExternalFunctionRequestHttpMethod.POST,
  path="/api/v1/resource",
  json={"key": "value"},
  headers={"extra-header-key": "extra-header-value"},
)

Usare le connessioni HTTP per gli strumenti dell'agente

Gli agenti di intelligenza artificiale possono usare la connessione HTTP per accedere ad applicazioni esterne come Slack, Google Calendar o qualsiasi servizio con un'API tramite richieste HTTP. Gli agenti possono usare strumenti connessi esternamente per automatizzare le attività, inviare messaggi e recuperare dati da piattaforme di terze parti.

Vedere Connettere gli strumenti dell'agente di intelligenza artificiale ai servizi esterni.

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2025-11-08