Condividi tramite

Pipeline di controllo del codice sorgente e distribuzione nell'API per GraphQL (anteprima)

Informazioni sul funzionamento delle pipeline di integrazione e distribuzione Git con l'API per GraphQL in Microsoft Fabric. Questo articolo illustra come configurare una connessione al repository, gestire l'API per GraphQL e distribuirle in ambienti diversi.

Chi usa il controllo del codice sorgente e la distribuzione

Le pipeline di integrazione e distribuzione Git sono essenziali per:

  • Data engineers che gestiscono le configurazioni dell'API Fabric GraphQL attraverso il controllo delle versioni e i flussi di lavoro di integrazione e distribuzione continua (CI/CD)
  • Amministratori di area di lavoro Fabric che coordinano le distribuzioni tra le aree di lavoro Fabric di sviluppo, test e produzione
  • Team DevOps che implementano pipeline di deployment per le Fabric APIs in più ambienti e capacità
  • Team della piattaforma che richiedono funzionalità di governance, rilevamento e rollback per le modifiche dell'API di Infrastruttura

Usare le pipeline di controllo del codice sorgente e di distribuzione quando è necessario gestire le API GraphQL come parte di un ciclo di vita di sviluppo strutturato con più ambienti.

Annotazioni

L'API per il controllo del codice sorgente GraphQL e la distribuzione sono attualmente in anteprima.

Prerequisiti

Informazioni generali

Fabric offre potenti strumenti per CI/CD (integrazione continua e distribuzione continua) e la gestione del ciclo di vita di sviluppo tramite due componenti principali: Integrazione Git (CI) e pipeline di distribuzione (CD). Le aree di lavoro fungono da componenti centrali per le fasi di sincronizzazione e distribuzione git.

Integrazione Git (CI): sincronizza gli elementi dell'area di lavoro (ad esempio, codice, configurazioni, API) con repository di controllo della versione, abilitando il controllo della versione e il rilevamento delle modifiche tramite Git.

Pipeline di distribuzione (CD): abilita la creazione di fasi (ad esempio, Sviluppo, Test, Produzione) con aree di lavoro collegate. Gli elementi supportati in ogni fase vengono replicati automaticamente nelle fasi successive, e le modifiche in un'area di lavoro attivano il deployment in una pipeline di rilascio. È possibile configurare la pipeline per assicurarsi che le modifiche vengano testate e distribuite in modo efficiente in ambienti diversi.

Fabric supporta diversi flussi di lavoro CI/CD personalizzati per scenari comuni. Per altre informazioni, vedere Opzioni del flusso di lavoro CI/CD in Fabric.

Annotazioni

Solo i metadati vengono copiati durante la distribuzione; e i dati non sono copiati.

Gli elementi dell'area di lavoro vengono archiviati nel repository Git associato come Infrastruttura come Codice (IaC). Le modifiche al codice nel repository possono attivare la distribuzione nelle pipeline. Questo metodo consente di replicare automaticamente le modifiche del codice tra le fasi per scopi di test e rilascio di produzione.

Metodi di autenticazione dell'origine dati

Quando si crea l'API per GraphQL, si sceglie come i client eseguono l'autenticazione e l'accesso alle origini dati. Questa scelta ha implicazioni significative per le pipeline di distribuzione e il comportamento di associazione automatica. Comprendere questi metodi di autenticazione è essenziale per pianificare il flusso di lavoro CI/CD. Per altre informazioni sull'associazione automatica e sul processo di distribuzione, vedere Informazioni sul processo di distribuzione.

Sono disponibili due opzioni di connettività per la connessione delle origini dati all'API per GraphQL: Single Sign-On (SSO) e Credenziali salvate.

Screenshot delle opzioni per la connessione GraphQL alle origini dati.

Autenticazione unica (SSO)

Con SSO, i client API usano le proprie credenziali per accedere alle origini dati. L'utente dell'API autenticata deve disporre delle autorizzazioni per l'API e l'origine dati sottostante.

Usare SSO quando:

  • Esposizione di origini dati di Fabric (lakehouse, warehouse, endpoint di analisi SQL)
  • Si vuole consentire agli utenti di accedere ai dati in base alle singole autorizzazioni
  • È necessaria la sicurezza a livello di riga o altri criteri di accesso ai dati da applicare per utente

Requisiti relativi alle autorizzazioni:

  • Per gli utenti dell'API sono necessarie autorizzazioni di esecuzione per l'API GraphQL (esecuzione di query e mutazioni)
  • Per gli utenti dell'API sono necessarie autorizzazioni di lettura o scrittura per l'origine dati
  • In alternativa, aggiungere gli utenti come membri dell'area di lavoro con il ruolo Collaboratore in cui si trovano sia l'API che l'origine dati

Comportamento di associazione automatica nelle pipeline di distribuzione: Quando si distribuisce un'API usando l'accesso SSO dall'area di lavoro di origine (ad esempio, Dev) all'area di lavoro di destinazione (ad esempio, Test):

  • L'origine dati e l'API GraphQL vengono entrambi distribuiti nell'area di lavoro di destinazione
  • L'API nell'area di lavoro di destinazione viene associata automaticamente alla copia dell'origine dati locale nell'area di lavoro di destinazione
  • Ogni ambiente (Sviluppo, Test, Produzione) usa la propria istanza dell'origine dati

Annotazioni

Esistono limitazioni specifiche quando si usa l'accesso SSO con gli endpoint di Analisi SQL. Per informazioni dettagliate, vedere Limitazioni correnti .

Credenziali salvate

Con le credenziali salvate, una singola credenziale condivisa esegue l'autenticazione tra l'API e le origini dati. Gli utenti dell'API devono accedere solo all'API stessa, non alle origini dati sottostanti.

Usare le credenziali salvate quando:

  • Esposizione di origini dati di Azure (database SQL di Azure, database esterni)
  • Si vuole una gestione semplificata delle autorizzazioni (gli utenti necessitano solo dell'accesso all'API)
  • Tutti gli utenti dell'API devono accedere agli stessi dati con le stesse autorizzazioni
  • Sono necessarie credenziali coerenti in tutte le richieste API

Requisiti relativi alle autorizzazioni:

  • Gli utenti dell'API necessitano solo delle autorizzazioni Di esecuzione per l'API GraphQL (esecuzione di query e mutazioni)
  • Le credenziali salvate devono disporre delle autorizzazioni appropriate per l'origine dati
  • Gli sviluppatori che distribuiscono l'API devono avere accesso alle credenziali salvate

Comportamento di associazione automatica nelle pipeline di distribuzione: Quando si distribuisce un'API usando credenziali salvate dall'area di lavoro di origine (Dev) all'area di lavoro di destinazione (test):

  • La sorgente dati è distribuita nell'area di lavoro di destinazione
  • L'API nell'area di lavoro di destinazione rimane connessa all'origine dati nell'area di lavoro di origine (Dev)
  • L'associazione automatica non si verifica : l'API distribuita continua a usare le credenziali salvate che puntano all'origine dati originale
  • È necessario riconfigurare manualmente le connessioni o creare nuove credenziali salvate in ogni ambiente di destinazione

Importante

Dopo aver scelto un metodo di autenticazione per l'API, si applica a tutte le origini dati aggiunte all'API. Non è possibile combinare l'accesso SSO e le credenziali salvate nella stessa API.

Connessioni tra aree di lavoro

Se l'API nell'area di lavoro di origine (Dev) si connette a un'origine dati in un'area di lavoro diversa, l'API distribuita nell'area di lavoro di destinazione (Test) rimane connessa a tale origine dati esterna indipendentemente dal metodo di autenticazione. L'associazione automatica funziona solo quando l'API e l'origine dati si trovano nella stessa area di lavoro di origine.

Il diagramma seguente illustra questi scenari di distribuzione:

Screenshot della pipeline per varie connessioni e scenari di origine dati.

Per altre informazioni sulla configurazione di questi metodi di autenticazione durante la creazione dell'API, vedere Connettersi a un'origine dati.

API GraphQL per l'integrazione di Git

L'API fabric per GraphQL supporta l'integrazione con Git, consentendo di gestire le API GraphQL come codice all'interno del sistema di controllo della versione. Questa integrazione fornisce la cronologia delle versioni, la collaborazione tramite rami e richieste pull, la possibilità di ripristinare le modifiche e un audit trail completo delle modifiche api. Considerando la configurazione dell'API GraphQL come infrastruttura come codice (IaC), è possibile applicare le procedure consigliate per lo sviluppo software al livello di accesso ai dati.

L'integrazione di Git è essenziale per:

  • Controllo della versione: tenere traccia di tutte le modifiche apportate allo schema GraphQL, alle connessioni all'origine dati e alle relazioni nel tempo
  • Collaborazione: collaborare con i membri del team usando rami, richieste pull e revisioni del codice
  • Funzionalità di rollback: ripristinare le configurazioni API precedenti quando si verificano problemi
  • Promozione dell'ambiente: usare Git come origine della verità per la distribuzione di API in ambienti diversi

Connettere l'area di lavoro a Git

Per abilitare l'integrazione git per le API GraphQL:

  1. Aprire le impostazioni dell'area di lavoro per l'area di lavoro contenente l'API per GraphQL
  2. Configurare la connessione Git al repository (Azure DevOps, GitHub o altro provider Git)
  3. Dopo la connessione, tutti gli elementi dell'area di lavoro, incluse le API per GraphQL, vengono visualizzati nel pannello di controllo Del codice sorgente

Per istruzioni dettagliate sull'installazione, vedere Introduzione all'integrazione con Git.

Screenshot dello stato dell'area di lavoro e del controllo del codice sorgente.

Eseguire il commit e la sincronizzazione delle API GraphQL

Dopo la connessione a Git, è possibile eseguire il commit dell'API per le configurazioni GraphQL nel repository. Ogni commit crea uno snapshot della definizione dell'API, tra cui:

  • Definizioni dello schema GraphQL
  • Connessioni all'origine dati e impostazioni di autenticazione
  • Configurazioni delle relazioni
  • Definizioni di query e mutazioni

Dopo il commit, le API GraphQL vengono visualizzate nel repository Git con una gerarchia di cartelle strutturata. A questo punto, è possibile sfruttare flussi di lavoro Git standard come la creazione di richieste pull, la gestione dei rami e la collaborazione con il team tramite revisioni del codice. Per altre informazioni sull'uso dei rami, vedere Gestire i rami.

Rappresentazione dell'API GraphQL in Git

Ogni API per l'elemento GraphQL viene archiviata in Git con una struttura di cartelle ben definita che rappresenta tutti gli aspetti della configurazione dell'API:

Screenshot della rappresentazione della struttura dei file in Git per GraphQL.

I file di definizione dell'API contengono tutti i metadati necessari per ricreare l'API GraphQL in qualsiasi workspace Fabric. Sono incluse le definizioni di schema, i mapping delle origini dati e le impostazioni di configurazione. Quando si esegue la sincronizzazione da Git a un'area di lavoro di Fabric, il sistema usa questi file di definizione per ripristinare l'API esattamente come quando è stato eseguito il commit:

Screenshot dell'API per le definizioni GraphQL archiviate in Git.

Uso dei file di definizione dell'API:

Il formato di definizione dell'API GraphQL segue gli standard IaC (Infrastructure as Code) di Fabric. È possibile visualizzare e modificare questi file direttamente nel repository Git, anche se la maggior parte delle modifiche deve essere apportata tramite il portale di Fabric per garantire la validità dello schema. I file di definizione sono particolarmente utili per:

  • Revisioni del codice: i membri del team possono esaminare le modifiche dell'API nelle richieste pull
  • Documentazione: i file fungono da documentazione della struttura dell'API
  • Automazione: le pipeline CI/CD possono leggere questi file per comprendere le configurazioni dell'API
  • Ripristino di emergenza: le definizioni api complete vengono mantenute nel controllo della versione

Per informazioni dettagliate sul formato, la sintassi e gli esempi di definizione dell'API GraphQL, vedere la documentazione sulle API del piano di controllo di Fabric:

API per GraphQL nella pipeline di distribuzione

Le pipeline di distribuzione consentono di alzare di livello l'API per le configurazioni GraphQL tra ambienti (in genere sviluppo, test e produzione). Quando si distribuisce un'API per GraphQL tramite una pipeline, vengono copiati solo i metadati dell'API, incluse le definizioni dello schema, le connessioni all'origine dati e le configurazioni delle relazioni. I dati effettivi rimangono nelle origini dati connesse e non sono copiati durante la distribuzione.

Considerazioni principali sulla distribuzione:

Prima della distribuzione, comprendere in che modo i metodi di autenticazione e l'organizzazione dell'area di lavoro influiscono sulla distribuzione:

  • Le API che usano Single Sign-On (SSO) possono eseguire l'associazione automatica alle origini dati locali nell'area di lavoro di destinazione (quando l'origine dati è stata distribuita anche dalla stessa area di lavoro di origine)
  • Le API che usano credenziali salvate non vengono collegate automaticamente e rimangono connesse all'origine dati dell'area di lavoro di origine
  • Le fonti di dati tra aree di lavoro diverse non si associano mai automaticamente, indipendentemente dal metodo di autenticazione

Per una comprensione completa del processo di distribuzione, vedere Informazioni sul processo di distribuzione.

Distribuire l'API di GraphQL

Per distribuire l'API per GraphQL usando le pipeline di distribuzione:

  1. Creare una nuova pipeline di distribuzione o aprirne una esistente. Per istruzioni dettagliate, vedere Introduzione alle pipeline di distribuzione.

  2. Assegnare le aree di lavoro alle fasi della pipeline (Sviluppo, Test, Produzione) in base alla strategia di distribuzione. Ogni fase deve avere un'area di lavoro dedicata.

  3. Esaminare e confrontare gli elementi tra le fasi. La pipeline mostra le API per GraphQL modificate, indicate dai conteggi degli elementi nelle aree evidenziate. Questo confronto consente di comprendere cosa sarà interessato dalla distribuzione.

    Screenshot della pipeline che illustra lo stato degli elementi in ogni fase di sviluppo.

  4. Selezionare le API per GraphQL e gli elementi correlati (ad esempio le origini dati connesse) da distribuire. Selezionare quindi Distribuisci per spostarli nella fase successiva.

    Screenshot della pipeline che mostra gli elementi selezionati che devono essere implementati.

  5. Esaminare la finestra di dialogo di conferma della distribuzione, che mostra tutti gli elementi da distribuire. Selezionare Distribuisci per continuare.

    Screenshot della pipeline che mostra il messaggio di conferma della distribuzione.

Limitazioni correnti

Quando si distribuiscono API per GraphQL tramite pipeline di distribuzione, l'associazione automatica presenta le limitazioni seguenti:

  • Elementi figlio: l'associazione automatica non funziona quando l'API si connette a un endpoint di Analisi SQL figlio di un'origine dati padre, ad esempio lakehouse. L'API distribuita rimane connessa all'endpoint dell'area di lavoro di origine.

  • Credenziali salvate: le API che usano il metodo di autenticazione delle credenziali salvate non supportano l'associazione automatica. L'API rimane connessa alla fonte dati dell'area di lavoro sorgente dopo la distribuzione.

Per informazioni dettagliate sui metodi di autenticazione e sul relativo comportamento di associazione automatica, vedere Metodi di autenticazione dell'origine dati.

Contenuto correlato

  • Last updated on