Condividi tramite

API di infrastruttura per la visualizzazione dello schema GraphQL ed Esplora schemi

L'API fabric per GraphQL genera automaticamente uno schema che definisce la struttura dell'API in base alle origini dati connesse. Lo schema, scritto in GraphQL Schema Definition Language (SDL), descrive tutti i tipi, i campi, le query e le mutazioni disponibili che i client possono usare per interagire con i dati.

La visualizzazione dello schema offre una visualizzazione basata su testo di sola lettura del tuo schema GraphQL completo, mentre l'esploratore di schemi nel riquadro sinistro consente di navigare, esaminare e modificare gli oggetti esposti tramite l'API. Insieme, questi strumenti consentono di comprendere la struttura dell'API e controllare quali dati sono accessibili ai client.

Chi usa la visualizzazione schema

La visualizzazione dello schema e lo strumento di esplorazione sono utili per:

  • Data engineers che configurano gli oggetti di Fabric lakehouse e warehouse da esporre tramite GraphQL
  • Sviluppatori di applicazioni che individuano i tipi di dati, i campi e le relazioni di Fabric disponibili prima di scrivere query
  • Collaboratori dell'area di lavoro Fabric che comprendono e gestiscono la struttura di accesso ai dati per la loro area di lavoro
  • Sviluppatori di business intelligence che esaminano le relazioni tra i dati di Fabric durante la creazione di applicazioni di analisi personalizzate

Usare la visualizzazione schema per esplorare la struttura dell'API e lo strumento di esplorazione dello schema per modificare gli oggetti dati esposti.

Accedere ed esplorare lo schema

È possibile accedere alla visualizzazione schema dall'editor di query o direttamente dall'elemento dell'API GraphQL. Per aprire la visualizzazione schema, selezionare Schema nell'angolo inferiore sinistro. La vista dello schema mostra una versione di sola lettura basata su testo del tuo file SDL GraphQL completo con tutti i tipi, i campi, le query e le mutazioni generati.

L'immagine seguente mostra la visualizzazione schema con il riquadro Esplora schemi a sinistra:

Screenshot della schermata di visualizzazione dello schema dell’API, che include Esplora schema nel riquadro sinistro.

Esplora schemi nel riquadro sinistro consente di esplorare ed esaminare tutti gli oggetti nell'API. L'esploratore è disponibile sia nella vista schema che nell'editor di query, consentendo di esplorare facilmente la struttura dell'API mentre si scrivono le query.

Espandere i nodi in Esplora schemi per visualizzare:

  • Tipi: Tipi GraphQL generati dalle tabelle e dalle viste della sorgente dati
  • Query: operazioni di lettura generate automaticamente per il recupero dei dati
  • Mutazioni: operazioni di scrittura generate automaticamente per la creazione, l'aggiornamento e l'eliminazione di dati (solo warehouse)

Tipi

I tipi rappresentano la struttura dei dati e vengono visualizzati sotto il nome dell'origine dati da cui sono stati generati. L'immagine seguente mostra il tipo SalesOrderDetail generato dalla tabella SalesOrderDetail nell'endpoint di analisi SQL AdventureWorks :

Screenshot del riquadro Esplora schemi che mostra l'elenco espanso di tipi disponibili in un'origine dati di esempio denominata SalesOrderDetail.

Queries

L'API genera automaticamente query per il recupero dei dati dagli oggetti esposti. Espandere il nodo query per visualizzare tutte le operazioni di lettura disponibili:

Screenshot del riquadro 'Esplora schema' che mostra un elenco espanso delle query generate automaticamente.

Mutazioni

Le mutazioni sono operazioni di scrittura per la creazione, l'aggiornamento e l'eliminazione di dati. Espandere il nodo delle mutazioni per visualizzare tutte le operazioni di scrittura disponibili:

Screenshot del riquadro Esplora schemi che mostra un elenco espanso di mutazioni generate automaticamente.

Nota

Le variazioni vengono generate solo per le origini dati del Fabric Data Warehouse. Gli endpoint di Analisi SQL (Lakehouse e database con mirroring) sono di sola lettura e supportano solo le query. Se non vengono visualizzate mutazioni in Esplora schemi, verificare di aver eseguito la connessione a un data warehouse di Fabric.

Modificare gli oggetti usando Esplora schemi

Dopo che l'API genera lo schema iniziale, è possibile usare Esplora schemi per perfezionare gli elementi esposti tramite l'API. Esplora schemi offre opzioni di gestione che consentono di controllare la struttura dell'API senza modificare le origini dati sottostanti. Questi strumenti sono essenziali per mantenere un'API pulita e ben organizzata che espone solo i dati necessari ai client.

Opzioni di modifica dell'accesso

Per modificare un oggetto, selezionare i puntini di sospensione (...) accanto a qualsiasi tipo nell'Esploratore di schemi. L'esempio seguente mostra il menu di modifica per il tipo SalesOrderDetail :

Screenshot dell'esploratore di schemi con l'ellissi selezionato, che mostra le opzioni disponibili nel menu.

Opzioni di modifica disponibili

Aggiorna schema : sincronizza lo schema GraphQL con la struttura più recente dall'origine dati. Utilizzare questa funzione quando sono state aggiunte nuove tabelle, viste o colonne all'origine dati e si desidera esporle tramite l'API. Questa operazione individua e aggiunge nuovi oggetti mantenendo al tempo stesso la configurazione esistente.

Rinomina : modifica la modalità di visualizzazione dell'oggetto nell'API GraphQL. Ciò è utile per creare convenzioni di denominazione api più intuitive o nascondere i dettagli di implementazione dai client. Ad esempio, è possibile rinominare tbl_SalesOrderDetail semplicemente SalesOrderDetail. La ridenominazione influisce solo sullo schema dell'API e non modifica l'oggetto origine dati sottostante.

Rimuovi dallo schema : rimuove l'oggetto dall'API GraphQL, rendendolo non disponibile ai client. Usare questa opzione per nascondere i dati sensibili, rimuovere oggetti deprecati o semplificare la superficie dell'API. I dati rimangono nella sorgente dati; viene rimossa solo un'esposizione dell'API.

Gestisci relazioni : apre l'interfaccia di gestione delle relazioni in cui è possibile definire il modo in cui gli oggetti si connettono tra loro. Le relazioni consentono query annidate e attraversamento grafico, consentendo ai client di recuperare i dati correlati in una singola richiesta. Per altre informazioni, vedere Gestire le relazioni nell'API Fabric per GraphQL.

Proprietà : visualizza metadati dettagliati sull'oggetto, incluso il nome originale visualizzato nell'origine dati, il nome del tipo GraphQL, il proprietario e la posizione (area di lavoro e nome origine dati). Usa questa opzione per verificare la mappatura degli oggetti tra l'origine dati e l'API GraphQL.

Abilitare e disabilitare query e mutazioni

La funzionalità di abilitazione o disabilitazione per query e mutazioni fornisce agli amministratori e agli sviluppatori un controllo granulare sull'accesso e l'utilizzo delle API. Consente di attivare o disattivare in modo selettivo query e mutazioni specifiche all'interno dello schema GraphQL. In questo modo è possibile gestire in modo dinamico le funzionalità dell’API senza modificare il codice o distribuire le modifiche.

Usare questa funzionalità per scenari come:

  • Controllo delle versioni api: disabilitare le operazioni deprecate durante la transizione dei client a nuove versioni
  • Finestre di manutenzione: disabilitare temporaneamente le operazioni di scrittura (mutazioni) durante la manutenzione dei dati
  • Sicurezza e conformità: limitare l'accesso alle operazioni sensibili senza rimuoverle dallo schema
  • Implementazioni in più fasi: abilitare nuove query o mutazioni per i test prima di renderle disponibili a livello generale

Le query e le mutazioni in Esplora schemi hanno due altre opzioni:

  • Disabilita: impedisce a qualsiasi richiesta di eseguire la query o la mutazione. Se viene tentata l'esecuzione, viene restituito un errore. Dopo aver disabilitato una query o una mutazione, si verifica un ricaricamento dello schema e la query o la mutazione viene visualizzata in grigio in Esplora schemi.

Screenshot dell'opzione disabilita query o mutazione visualizzata in Esplora schemi.

  • Abilita: consente di riabilitare una query o una mutazione disabilitata in precedenza. La query o la mutazione è immediatamente disponibile dopo l'operazione di ricaricamento dello schema che si verifica quando si seleziona l'opzione Abilita .

Screenshot dell'opzione abilita query di modifica visualizzata in Schema Explorer.

Nota

Le query e le mutazioni generate automaticamente dalle stored procedure si comportano in modo diverso rispetto a quelle generate da tabelle o viste. Possono essere eliminati solo, non disabilitati. Dopo l'eliminazione, è possibile leggerli usando le opzioni Recupera dati o Aggiorna schema . Per altre informazioni, vedere Stored procedure.

Contenuto correlato

  • Last updated on