Usa Genie ovunque con Enterprise OAuth

Introduzione

La democratizzazione dei dati inizia con un accesso alle informazioni dettagliate facile e sicuro. Con Databricks Genie, gli utenti possono ora interagire con i dati direttamente dagli strumenti che già utilizzano: Teams, Slack, Confluence o app web personalizzate. Sia che si utilizzino le nostre integrazioni native Copilot Studio/Foundry o si creino soluzioni con le API/SDK di Genie Conversation, Genie può ora portare le analitiche in linguaggio naturale nei flussi di lavoro di tutti i giorni. Dietro le quinte, è possibile applicare OAuth per autenticare in modo sicuro ogni utente e applicare le autorizzazioni di accesso ai dati.

In precedenza, abbiamo visto clienti come The AA e Casas Bahia creare in modo indipendente le proprie integrazioni di Genie in Microsoft Teams e nelle app interne. La nostra solida suite di estensibilità ora rende questa esperienza più facile, veloce e scalabile.

In questo blog illustreremo due modi comuni per implementare Genie con OAuth aziendale nella tua organizzazione:

• Porta Genie in Microsoft Teams con la nostra integrazione di Copilot Studio
• Integra Genie nelle tue app Web personalizzate con le API Genie Conversation

Porta Genie in Microsoft Teams

Le domande ad hoc sui dati vengono poste di continuo durante le conversazioni di gruppo. Con l'integrazione nativa di Databricks Genie in Copilot Studio, i tuoi utenti possono ora ottenere risposte non appena sorgono domande, direttamente in Microsoft Teams. Per sfruttare questa integrazione, segui i passaggi riportati di seguito:

Prerequisiti

• Assicurati di avere uno spazio Genie di destinazione curato secondo le nostre best practice per offrire la massima qualità.
• Gli utenti finali/i Service Principals devono avere accesso allo Genie space di destinazione (almeno CAN VIEW), i privilegi SELECT sui dati di Unity Catalog dello spazio e l'autorizzazione CAN USE per il SQL compute dello spazio. Agli utenti finali può essere facoltativamente assegnata l'autorizzazione Accesso consumer per un'esperienza semplificata di "sola lettura".

Passaggio 1: Connetti Azure Databricks a Power Platform

Il primo passaggio per abilitare Genie in Microsoft Teams consiste nel connettere Azure Databricks a Power Platform (documentazione). Nelle tue app Microsoft Power Apps, fai clic su Connessioni e seleziona Azure Databricks o Databricks se usi AWS/GCP. Configura i seguenti campi:

• Per garantire che ogni utente finale si autentichi in Databricks con la propria identità, selezionare OAuth come tipo di autenticazione.
• Per il Hostname del Server e il percorso HTTP, vai al workspace in cui si trova il tuo Genie space di destinazione. Seleziona un'istanza di SQL warehouse e apri i Dettagli di connessione per recuperare queste informazioni (non è necessario che sia la stessa istanza di SQL warehouse collegata al tuo spazio Genie).

Passaggio 2: connetti gli spazi Genie al tuo agente Copilot Studio

Successivamente, connetterai il tuo spazio Genie a Copilot Studio (documentazione). La nostra integrazione gestisce tutta la logica delle API e di MCP, quindi la connessione può essere effettuata in pochi clic.

In Copilot Studio, fare clic su Agenti. Selezionare “Crea agente vuoto” per creare un nuovo agente autonomo per uno spazio Genie. Se si desidera integrare Genie in un framework di agenti esistente, è anche possibile scegliere un agente Copilot Studio esistente a cui aggiungere il proprio Genie space.

Nel tuo nuovo agente, fai clic su 'Strumenti', quindi su "Aggiungi uno strumento". Seleziona Azure Databricks Genie (o Databricks Genie per AWS/GCP) nella sezione MCP.

Ora, puoi selezionare lo spazio Genie desiderato e configurare i dettagli della connessione:

• Credenziali da utilizzare: selezionare "Credenziali utente finale" per garantire che ogni utente dell'applicazione effettui l'accesso con la propria identità e le proprie autorizzazioni di accesso ai dati. Ciò garantisce che se un utente dell'applicazione non ha accesso allo spazio Genie o alle tabelle, non sarà in grado di recuperare informazioni dettagliate sui dati da Genie.
• Seleziona “Credenziali fornite dall'autore” se vuoi che gli utenti finali si autentichino utilizzando un'unica identità condivisa (un'entità servizio, consigliata, o la tua identità).
• IMPORTANTE: assicurati che il tuo spazio Genie di destinazione abbia un titolo e una descrizione chiari che ne delineino il contesto, i concetti chiave e le limitazioni. Questo aiuterà il tuo agente Copilot Studio a orchestrare efficacemente le richieste.

Passaggio 3: Abilita la condivisione dei parametri di connessione

Quando si sceglie "Credenziali utente finale", ogni persona deve accedere a Databricks con il proprio account. Per semplificare l'operazione, suggeriamo di condividere i parametri di connessione (come descritto nella documentazione Microsoft), in modo che gli utenti non debbano fornire tali informazioni da soli. In pratica, ciò significa semplicemente fornire il server Hostname e il percorso HTTP, il che garantisce che l'autenticazione avvenga nell'area di lavoro Databricks esatta collegata allo spazio Genie connesso nell'agente Copilot Studio.

• Apri la pagina Impostazioni del tuo agente di Copilot Studio.
• Apri le impostazioni di connessione e assicurati che Azure Databricks mostri lo stato Connesso.
  
• Quindi, fare clic su Vedi dettagli e consentire la condivisione dei parametri nella scheda Parametri di connessione.
  

Passaggio 4: Porta il tuo agente in Teams

Ora che disponi di un agente Copilot Studio connesso al tuo spazio Genie, puoi pubblicarlo su Teams.

• Assicurati che il tuo agente abbia un Nome e una Descrizione chiari.
• Consigliamo inoltre:
  • Selezione di un modello di ragionamento (ad es. Ragionamento di GPT-5, Claude Sonnet 4.5) per un polling efficace e l'uso di Genie.
  • Aggiunta di istruzioni personalizzate per l'agente per personalizzare l'esperienza (ad es. formattazione delle risposte e preferenze di latenza).
    
• Dopo aver esaminato il tuo agente di Copilot Studio, fai clic su Pubblica. Quindi, in Canali, scegli Teams come canale desiderato.
  

Tutto a posto! Genie è ora attivo in Microsoft Teams e fornisce informazioni dettagliate sui dati governati nel momento stesso in cui sorgono le domande.

Per vedere come gli utenti finali utilizzano Genie in Microsoft Teams, consulta le nostre storie dei clienti.

Integrazione di Genie nelle applicazioni web personalizzate

Molte organizzazioni vogliono anche integrare Genie direttamente nelle loro app web personalizzate, in modo che gli utenti possano porre domande negli strumenti che già utilizzano; ad esempio, i responsabili dei punti vendita potrebbero porre domande ad hoc sul loro inventario direttamente nel terminale di vendita esistente. Con le API di conversazione di Genie e l'OAuth di Databricks, ora questo è possibile.

Prima di creare un'integrazione tra la tua app Web e Genie, è importante decidere quale modello OAuth utilizzare: User-to-Machine (U2M), Machine-to-Machine (M2M) o On-Behalf-Of (OBO). Ciascun approccio è in linea con un diverso tipo di caso d'uso dell'applicazione:

• User-to-Machine (U2M) - Ideale quando ogni utente finale necessita di un accesso ai dati gestito e personalizzato. In questo modello, un utente accede con la propria identità aziendale (ad es. SSO), Genie riceve un token OAuth specifico per l'utente e le query vengono eseguite con le autorizzazioni di tale utente. Caso d'uso di esempio: un Copilot per le vendite in cui gli addetti alle vendite chattano con un singolo Genie space sottostante e dovrebbero visualizzare solo le informazioni dettagliate sui dati dalle proprie trattative.
• Da macchina a macchina (M2M) - Ideale per i casi d'uso in cui si desidera che tutti gli utenti abbiano lo stesso accesso ai dati e una governance più semplice. Questo modello consente a un'entità servizio di autenticarsi e di rilasciare un token OAuth associato a Genie, che viene quindi utilizzato per eseguire query con le autorizzazioni dell'entità servizio. Esempio di caso d'uso: un chatbot per i "KPI aziendali" in cui qualsiasi dipendente può porre domande sulle metriche KPI a livello aziendale e ricevere le stesse informazioni dettagliate condivise.
• On-Behalf-Of (OBO): ideale per le app che necessitano di una governance dei dati per utente, ma dietro a un backend centrale. In questo modello, l'applicazione si autentica prima in Databricks e poi chiama le API di Genie "per conto" dell'utente finale, applicando le sue autorizzazioni sui dati. Caso d'uso di esempio: un portale di analitiche finanziarie in cui gli utenti chattano con un chatbot unificato che sfrutta Genie e ogni utente vede solo i dati per cui è autorizzato.

Nel resto di questo blog, ci concentreremo sul primo modello per l'integrazione con Genie: il flusso OAuth U2M che utilizza il supporto OAuth integrato di Databricks.

NOTA: Databricks supporta anche la federazione dei token OAuth, che è possibile utilizzare per importare i token emessi dal proprio provider di identità e combinarli con uno qualsiasi dei metodi descritti sopra per l'accesso a Genie.

Prerequisiti

• Assicurati di avere uno spazio Genie di destinazione curato secondo le nostre best practice per offrire la massima qualità.
• Gli utenti finali/i Service Principal devono avere accesso allo spazio Genie di destinazione (almeno CAN VIEW), i privilegi SELECT sui dati di Unity Catalog dello spazio e l'autorizzazione CAN USE sulla risorsa di calcolo SQL dello spazio. Agli utenti finali può essere facoltativamente assegnata l'autorizzazione Consumer Access per un'esperienza semplificata di "sola lettura".
  

Passaggio 1: Registra un'applicazione OAuth

Per connettere in modo sicuro la tua app Web personalizzata a Genie, inizia registrandola nel tuo account Databricks. Questo passaggio consente a Databricks di emettere in modo sicuro token con ambito utente per la tua app nei passaggi successivi. Consulta la documentazione del prodotto per saperne di più.

Nella console dell'account Databricks, aggiungere una nuova connessione OAuth e configurare quanto segue:

• Nome applicazione: un nome leggibile mostrato agli utenti durante l'accesso
• URL di reindirizzamento: uno o più URL a cui Databricks è autorizzato a inviare gli utenti dopo l'autenticazione. Questi devono corrispondere esattamente agli URL che la tua app utilizzerà nei passaggi successivi.
• Ambiti di accesso: concedi l'accesso a tutte le API in modo che la tua app possa chiamare le API di conversazione di Genie per conto degli utenti.
  

Dopo aver salvato questa connessione, Databricks genererà quanto segue:

• ID client: identificatore pubblico per la tua app
• Client Secret: credenziale privata per il tuo backend

Archivia queste credenziali in modo sicuro nel tuo backend: saranno necessarie per scambiare i codici di autorizzazione con token di accesso e per autenticare le chiamate alle API di conversazione di Genie.

Passaggio 2: indirizza gli utenti a Databricks per l'autenticazione e la concessione dell'accesso

Il passaggio successivo è assicurarsi che la propria app reindirizzi gli utenti finali a Databricks in modo che possano accedere e approvare la propria app per comunicare con Genie per loro conto. Dopo un accesso e un'approvazione riusciti, Databricks reindirizzerà l'utente alla tua app con un codice di autorizzazione di breve durata.

Questo codice di autorizzazione è la prova che l'utente si è autenticato correttamente in Databricks e ha approvato l'accesso richiesto dalla tua app. Il backend della tua app utilizzerà questo codice di autorizzazione nel passaggio successivo per ottenere i token di accesso.

Per iniziare, genera valori PKCE e di stato per ogni accesso per proteggere la tua applicazione web:

• Genera un code_verifier e un code_challenge corrispondente secondo lo standard OAuth PKCE utilizzando SHA-256 e la codifica URL Base64. Questo passaggio impedisce che i codici di autorizzazione vengano rubati e riutilizzati (vedi esempi di codice nella documentazione).
• Crea una stringa di stato casuale e assicurati di salvarla in un cookie o in una sessione. Ciò garantisce che i codici di autorizzazione vengano generati per sessioni utente finali reali.

Successivamente, il frontend dovrebbe costruire un URL di autorizzazione utilizzando l'endpoint OAuth di Databricks:

Includi i seguenti parametri del modulo per identificare la tua applicazione per i tuoi utenti:

• <databricks-instance>: la tua istanza Databricks con il workspace nome dell'istanza (ad es. dbc-a1b2345c-d6e7.cloud.databricks.com)
• <client_id>: l'ID client della tua applicazione OAuth registrata nel passaggio precedente
• <redirect-url>: lo stesso URL di reindirizzamento specificato nel passaggio precedente
• <state>: una qualsiasi stringa di testo semplice per convalidare la risposta
• <code-challenge>: challenge di codice PKCE derivato dal code_verifier

Dopo che un utente ha effettuato l'accesso al proprio account Databricks, verrà reindirizzato a redirect_url con i parametri di query: https://<redirect_url>/oauth/callback?code=<authorization_code>&state=<state>

Il gestore di callback dovrebbe leggere l'authorization_code e lo state dalla stringa di query. Verifica che il valore di state corrisponda a quanto memorizzato nei cookie o nelle sessioni web. In caso contrario, scarta l'authorization_code. Con il authorization_code restituito, la tua applicazione può ora scambiarlo con token di accesso.

Passaggio 3: scambia i codici di autorizzazione con i token e gestiscili in modo sicuro

Il codice di autorizzazione recuperato nel passaggio precedente non può essere utilizzato per chiamare direttamente le APIs, ma deve essere scambiato con token di accesso sul backend, necessari per comunicare in modo sicuro con Genie. Per ulteriori informazioni, consulta la nostra documentazione del prodotto).

Di seguito è riportato un esempio di Python per lo scambio di codici di autorizzazione con token di accesso e di refresh (per maggiori dettagli, vedi la documentazione dell'SDK OAuth):

Includi i seguenti parametri:

• <databricks-instance>: la tua istanza di Databricks con il nome dell'istanzadel workspace
• <client_id>: l'ID client della tua applicazione OAuth registrata nel passaggio precedente
• <client_secret>: il segreto client per la tua app generato nel Passaggio 1
• <redirect-url>: lo stesso URL di reindirizzamento specificato nel Passaggio 1
• <code-verifier>: il verifier generato nel passaggio 2

È importante salvare i seguenti valori dall'oggetto result nel database dell'app:

• access_token: utilizzato per chiamare le API di conversazione di Genie.
• refresh_token: utilizzato per ottenere nuovi token di accesso senza costringere l'utente a effettuare nuovamente l'accesso
• expires_in: un tempo di scadenza per il token di accesso
• expires_at: un timestamp che indica quando il token di accesso non è più valido

Per gestire in modo sicuro i token di accesso, è anche importante che l'app tenga traccia delle scadenze e utilizzi i token di aggiornamento per ottenere nuovi token di accesso quando necessario. L'esempio di codice seguente astrae la logica di refresh per restituire sempre un token di accesso utente valido:

Passaggio 4: Instrada i prompt degli utenti alle API di conversazione di Genie

Ora che la tua applicazione dispone di token di accesso a Databricks con ambito utente, può inviare prompt a uno spazio Genie per conto dell'utente che ha effettuato l'accesso. Consigliamo di creare un router API di backend per la tua applicazione web per proteggere i token di accesso a Databricks dal browser e per centralizzare l'osservabilità, la gestione degli errori e la limitazione della velocità. Gli esempi di codice riportati di seguito sfruttano FastAPI e l'SDK di Genie per una logica più semplice.

• Innanzitutto, utilizza il token di accesso dell'utente per creare un WorkspaceClient con ambito definito. Questo WorkspaceClient sarà quindi in grado di chiamare il Genie SDK. Esempi di codice

• Successivamente, esporre gli endpoint HTTP di proprietà dell'applicazione che si traducono in chiamate all'SDK di Genie nel backend. Ciò garantisce che tutte le chiamate all'SDK di Genie vengano effettuate all'interno del proprio server e che i token di accesso non vengano mai inviati al browser.
  • Ad esempio, ecco come creare un endpoint HTTP per avviare una nuova conversazione con Genie:

• Continua ad aggiungere altri router API per le azioni Genie che desideri che la tua app supporti. Le funzioni essenziali da includere sono:
  • Invia messaggio di follow-up: per i messaggi di follow-up a una conversazione esistente
    • create_message_and_wait(space_id: str, conversation_id: str, content: str, timeout: datetime.timedelta = 0:20:00) → GenieMessage
  • Recupera i risultati della query - recupera i risultati SQL se il messaggio ha un allegato di query
    • get_message_attachment_query_result(space_id: str, conversation_id: str, message_id: str, attachment_id: str) → GenieGetMessageQueryResultResponse
  • Ottieni messaggio - recupera stati e risultati per un messaggio specifico
    • get_message(space_id: str, conversation_id: str, message_id: str) → GenieMessage
  • Elenca i messaggi in una conversazione - per elencare tutti i messaggi precedenti in una conversazione
    • list_conversation_messages(space_id: str, conversation_id: str [, page_size: Optional[int], page_token: Optional[str]]) → GenieListConversationMessagesResponse
  • Consulta la documentazione dell'SDK di Genie per tutte le funzioni disponibili.

Dopo questi passaggi, la tua app Web personalizzata sarà integrata in modo sicuro con Genie, consentendo agli utenti di porre domande in linguaggio naturale e recuperare informazioni dettagliate gestite direttamente negli strumenti che già utilizzano.

Accedi a Genie ovunque

Genie è progettato per raggiungere gli utenti ovunque lavorino. In questo blog abbiamo illustrato come le organizzazioni incorporano in modo sicuro le funzionalità di analitiche conversazionali di Genie in Microsoft Teams e app personalizzate con l'autenticazione OAuth.

Portando Genie ovunque i tuoi team pongano domande, accorci il percorso dalla domanda all'approfondimento e dall'approfondimento all'azione. Inizia a creare spazi Genie e a metterli a disposizione dei tuoi utenti oggi stesso. Come sempre, per domande e feedback contatta i team del tuo account Databricks.

(Questo post sul blog è stato tradotto utilizzando strumenti basati sull'intelligenza artificiale) Post originale