Connettere le applicazioni all'API Fabric per GraphQL

La connessione di applicazioni all'API di Fabric per GraphQL consente alle applicazioni Web, per dispositivi mobili e back-end di eseguire query su origini dati di Fabric usando un'API moderna ed efficiente. Questa integrazione richiede l'autenticazione corretta tramite Microsoft Entra ID e configurazione dell'applicazione per chiamare l'endpoint GraphQL in modo sicuro.

Questo articolo illustra come connettere un'applicazione React all'API GraphQL di Fabric tramite:

1. Creazione e configurazione di un'app Microsoft Entra per l'autenticazione
2. Configurazione di un'API GraphQL di esempio in Fabric con dati su cui eseguire query
3. Clonazione e configurazione di un'applicazione React completa da GitHub
4. Test della connessione autenticata

L'esercitazione usa React, ma i concetti di autenticazione si applicano a qualsiasi linguaggio. Per esempi in C#, Python o altri linguaggi, vedere il repository GitHub degli esempi di Microsoft Fabric.

Chi deve connettere le applicazioni

La configurazione della connessione dell'applicazione è essenziale per:

• Sviluppatori Web e per dispositivi mobili che creano applicazioni che usano i dati dei lakehouse e dei magazzini di Fabric
• Sviluppatori di integrazione che connettono i dati di Fabric ad applicazioni personalizzate e flussi di lavoro automatizzati
• Sviluppatori back-end che creano servizi che si integrano con la piattaforma di analisi unificata di Fabric
• Data engineers che configurano flussi di lavoro automatizzati per l'elaborazione dati che consumano i dati di Fabric tramite API

Usare questa guida quando è necessario autenticare e autorizzare le applicazioni ad accedere alle API GraphQL di Fabric.

Prerequisiti

• Strumenti di sviluppo: sono necessari Node.js (versione LTS) e Visual Studio Code installati nel computer.

• Prima di connettere un'applicazione, assicurarsi di avere un'API per GraphQL in Fabric. Per altre informazioni, si veda Creare un'API per GraphQL in Fabric e aggiungere dati.

• L'API per GraphQL richiede che le applicazioni usino Microsoft Entra per l'autenticazione. Registrare e configurare l'applicazione per eseguire chiamate API su Fabric. Per altre informazioni, si veda Creare un'app Microsoft Entra in Azure.

• Le credenziali autenticate (entità utente, entità servizio o identità gestita) che chiamano l'API devono avere autorizzazioni di esecuzione per l'API GraphQL (opzione Esegui query e mutazioni quando si aggiungono autorizzazioni di accesso diretto). Se si usa Single Sign-On (SSO) come opzione di connettività nell'API, assicurarsi che le credenziali dispongano di autorizzazioni di lettura o scrittura nell'origine dati scelta. Per altre informazioni, vedere Connetti a un'origine dati e crea lo schema.

Riepilogo delle autorizzazioni e dell'autenticazione

L'accesso all'API GraphQL richiede l'autenticazione e l'autorizzazione appropriate sia a livello di API che a livello di origine dati sottostante. È possibile eseguire l'autenticazione usando un'entità utente (che rappresenta un singolo utente) o un'entità servizio (che rappresenta un'applicazione o un servizio). Per la connettività dell'origine dati, è possibile usare Single Sign-On (SSO) in cui l'identità del chiamante viene passata all'origine dati o le credenziali salvate in cui viene usata una connessione preconfigurata.

La tabella seguente riepiloga i diversi scenari di autenticazione supportati e le autorizzazioni minime necessarie per i client che accedono all'API GraphQL:

Chiamante API	Connettività dell'origine dati	Autorizzazioni api GraphQL necessarie	Autorizzazioni necessarie per l'origine dati	Ambito dell'app Microsoft Entra
Entità utente (UPN)	Autenticazione unica (SSO)	Eseguire query e mutazioni a livello di API	Autorizzazioni di lettura/scrittura appropriate concesse all'UPN nell'origine dati	GraphQLApi.Execute.All
Entità servizio (SPN)	Autenticazione unica (SSO)	Eseguire query e mutazioni a livello di API	Autorizzazioni di lettura/scrittura appropriate concesse al nome SPN nell'origine dati	Non applicabile
Entità utente (UPN)	Credenziali salvate	Eseguire query e mutazioni a livello di API	Autorizzazioni di lettura/scrittura appropriate concesse alle credenziali salvate (connessione) nell'origine dati	GraphQLApi.Execute.All
Entità servizio (SPN)	Credenziali salvate	Eseguire query e mutazioni a livello di API	Autorizzazioni di lettura/scrittura appropriate concesse al nome SPN nell'origine dati	Non applicabile

Creare un'app Microsoft Entra

Prima che l'applicazione possa chiamare l'API GraphQL di Fabric, è necessario registrarla in Microsoft Entra ID. Questa registrazione crea un'identità per l'applicazione e definisce le autorizzazioni necessarie. Il processo di registrazione genera un ID client (identificatore dell'applicazione) e stabilisce il flusso di autenticazione usato dall'app per ottenere i token di accesso.

Per le applicazioni React, si configurano le impostazioni dell'applicazione a pagina singola che usano il flusso PKCE, un metodo di autenticazione sicuro progettato per le app basate su browser in cui i segreti client non possono essere archiviati in modo sicuro.

1. Registrare un'applicazione usando i passaggi descritti in Avvio rapido: Registrare un'applicazione con Microsoft Identity Platform.

2. I valori ID applicazione (client) e ID Directory (tenant) dell'app Microsoft Entra vengono visualizzati nella casella Riepilogo. Registrare questi valori perché sono necessari quando si configura l'applicazione React.

3. Configurare le autorizzazioni API in modo che l'applicazione possa accedere all'API GraphQL di Fabric. Nell'elenco Gestisci selezionare autorizzazioni API , quindi Aggiungi autorizzazione.

4. Aggiungere il servizio PowerBI, selezionare Autorizzazioni delegate e selezionare le autorizzazioni GraphQLApi.Execute.All. Questa autorizzazione consente all'applicazione di eseguire query e mutazioni per conto dell'utente connesso. Verificare che il consenso dell'amministratore non sia obbligatorio.

5. Tornare all'elenco Gestisci, selezionare Autenticazione>Aggiungi una piattaforma>applicazione a pagina singola.

6. Ai fini dello sviluppo locale, aggiungere http://localhost:3000 in URI di reindirizzamento e verificare che l'applicazione sia abilitata per il flusso del codice di autorizzazione con la chiave di prova per Lo scambio di codice (PKCE). Selezionare il pulsante Configura per salvare le modifiche. Se l'applicazione rileva un errore correlato alle richieste tra le origini, aggiungere la piattaforma applicazioni per dispositivi mobili e desktop nel passaggio precedente con lo stesso URI di reindirizzamento.

7. Tornare a Authentication, scorrere verso il basso fino a Advanced Settings e, in Consenti flussi client pubblici, selezionare Sì per Abilitare i flussi per dispositivi mobili e desktop seguenti.

Impostare un'API GraphQL di esempio per l'accesso all'applicazione

Dopo aver registrato l'app Microsoft Entra, è necessaria un'API GraphQL in Fabric per eseguire query. Questa sezione illustra come creare un'API di esempio usando il set di dati delle festività pubbliche di Fabric. In questo modo è disponibile un'API funzionante per testare l'autenticazione e il recupero dei dati senza dover configurare le proprie origini dati.

L'API di esempio espone i dati delle festività da una tabella Lakehouse, che l'applicazione React interroga per visualizzare i giorni festivi.

1. Nella home page del portale di Infrastruttura selezionare Ingegneria dei dati dall'elenco dei carichi di lavoro.

2. Nell'esperienza di ingegneria dei dati selezionare Usa un esempio e in Lakehouse selezionare Festività pubbliche per creare automaticamente un nuovo Lakehouse con dati festivi pubblici.

   

3. Seguire la procedura descritta in Creare un'API per GraphQL per creare una nuova API GraphQL e selezionare il Lakehouse creato. Aggiungere la tabella festività pubblica in modo che i client possano accedere a questi dati.

   

4. Prima di compilare l'applicazione React, verificare che l'API funzioni correttamente testandola nell'editor api. Usare la query seguente: questa è la stessa query eseguita dall'applicazione React in un secondo momento:

    query {
    publicholidays (filter: {countryRegionCode: {eq:"US"}, date: {gte: "2024-01-01T00:00:00.000Z", lte: "2024-12-31T00:00:00.000Z"}}) {
        items {
          countryOrRegion
          holidayName
          date
        }
      }
    }
   

5. Selezionare Copia endpoint sulla barra degli strumenti dell'elemento API.

   

6. Nella schermata Copia collegamento selezionare Copia.

   

7. Registrare l'ID client e l'ID tenant dall'applicazione Microsoft Entra e dall'URI dell'endpoint. Questi valori sono necessari quando si configura l'applicazione React.

Clonare e configurare l'applicazione React

Dopo aver configurato l'app Microsoft Entra e l'API GraphQL, è possibile configurare un'applicazione React per la connessione. L'applicazione usa Microsoft Authentication Library (MSAL) per gestire l'autenticazione e effettua richieste GraphQL con token bearer.

1. Clonare il repository di esempi da GitHub:

   git clone https://github.com/microsoft/fabric-samples.git
   

2. Passare alla cartella dell'applicazione React:

   cd fabric-samples/docs-samples/data-engineering/GraphQL/React
   

   La cartella contiene un'applicazione React completa. È sufficiente modificare src/authConfig.js per configurare l'endpoint e le credenziali specifici.

3. Aprire il progetto nell'editor di codice:

   code .
   

4. Nell'editor passare alla src cartella e aprire authConfig.js.

5. Sostituire i valori segnaposto seguenti con i dettagli specifici:

   • Enter_the_GraphQL_Endpoint_Here - Sostituire con l'endpoint dell'API GraphQL da Configurare un'API GraphQL di esempio per l'accesso alle applicazioni
   • Enter_the_Application_Id_Here - Sostituire con l'ID applicazione (client) da Creare un'app Microsoft Entra
   • Enter_the_Tenant_Info_Here - Sostituire con l'ID directory (tenant) da Crea un'app Microsoft Entra

   Importante

   Nello stesso file la loginRequest costante include l'ambito https://analysis.windows.net/powerbi/api/GraphQLApi.Execute.All. Questo ambito esatto è necessario per accedere alle API GraphQL di Fabric. Non rimuovere o modificare questo ambito; in caso contrario, l'autenticazione non riesce.

6. Salvare il file.

7. Nel terminale passare alla cartella radice del progetto ed eseguire:

   npm install
   

   In questo modo vengono installate tutte le dipendenze necessarie.

Testare l'applicazione

Dopo aver configurato l'applicazione, eseguirla localmente per verificare che tutto funzioni correttamente:

1. Nel terminale eseguire:

   npm start
   

   Questo comando avvia il server di sviluppo e apre l'applicazione nel browser.

2. Completare il flusso di autenticazione quando l'applicazione viene caricata in http://localhost:3000. Seguire i passaggi di accesso descritti nella sezione esercitazione Chiamare l'API dall'applicazione.

3. Dopo aver eseguito l'accesso, selezionare il pulsante Query Fabric API for GraphQL Data (API di Query Fabric per i dati GraphQL ). Questo attiva il flusso di autenticazione, acquisisce un token di accesso ed esegue la query GraphQL sull'API di Infrastruttura.

   

4. Se tutto è configurato correttamente, l'applicazione visualizza le festività pubbliche in una tabella. Ciò conferma che:

   • L'app Microsoft Entra dispone delle autorizzazioni corrette
   • Il token di accesso è stato acquisito correttamente
   • L'API GraphQL ha autenticato la richiesta
   • Query eseguita sui dati del Lakehouse

   

Altri comandi npm

Oltre npm start a e npm install, è possibile usare questi comandi npm comuni per diversi scenari di sviluppo:

• npm run dev - Modo alternativo per avviare il server di sviluppo
• npm run build - Creare una build di produzione ottimizzata della tua applicazione
• npm run preview - Testare la compilazione di produzione in locale prima della distribuzione
• npm test - Eseguire test automatizzati per verificare il corretto funzionamento del codice

Contenuto correlato

Dopo aver creato un'applicazione funzionante connessa all'API GraphQL di Fabric, esplorare queste risorse per creare soluzioni più sofisticate:

• Creare un'API per GraphQL in Fabric e aggiungere dati - Informazioni su come esporre le proprie origini dati
• Eseguire query su più origini dati nell'API fabric per GraphQL - Combinare dati da origini diverse in una singola query
• API di infrastruttura per l'editor GraphQL - Testare e sviluppare query in modo interattivo
• Creare un'app Microsoft Entra in Azure - Guida dettagliata per la registrazione dell'app di produzione
• Esempi di GraphQL di Microsoft Fabric - Esplorare esempi in più lingue