Condividi tramite

API Fabric per l'introspezione e l'esportazione dello schema GraphQL

Quando si compilano applicazioni o si integrano strumenti esterni con l'API fabric per GraphQL, è necessario comprendere la struttura dell'API, quali tipi sono disponibili, quali campi contengono e come sono correlati tra loro. Indipendentemente dal fatto che si generi codice client, si crei la documentazione o si configurino gli strumenti di gestione API, l'accesso alla definizione dello schema è essenziale.

L'API fabric per GraphQL fornisce due meccanismi complementari per recuperare informazioni sullo schema: introspezione per le query di runtime a livello di codice ed esportazione dello schema per ottenere un file di schema completo. Entrambi i metodi offrono l'accesso allo stesso schema sottostante, ma ognuno serve flussi di lavoro e casi d'uso diversi.

Suggerimento

Vuoi vedere introspezione in azione? Prova l'esercitazione Connettere gli agenti di intelligenza artificiale all'API di Fabric per GraphQL con un server locale MCP (Model Context Protocol). Questa guida pratica illustra come gli agenti di intelligenza artificiale usano l'introspezione per individuare ed eseguire automaticamente query sui dati di Fabric usando il linguaggio naturale.

Utenti che usano introspezione ed esportazione dello schema

L'introspezione e l'esportazione dello schema sono utili per:

  • Sviluppatori di applicazioni che creano client che usano i dati di Fabric e devono generare codice tipo sicuro
  • Contributori del Fabric Workspace: comprensione delle strutture dati disponibili e test sull'accesso ai dati
  • Strumenti di sviluppo e IDE che forniscono il completamento automatico e IntelliSense per le API GraphQL di Fabric
  • Integrazioni di Gestione API di Azure che instradano e proteggono il traffico GraphQL di Fabric a livello aziendale
  • Amministratori dell'infrastruttura che controllano le strutture di dati esposte e convalidano i controlli di accesso
  • Agenti e assistenti di intelligenza artificiale che usano il protocollo MCP (Model Context Protocol) per individuare ed eseguire query sui dati di Fabric in modo naturale
  • Gli sviluppatori di Power Platform devono comprendere gli schemi di dati di Fabric prima di creare integrazioni
  • Pipeline CI/CD che monitora le versioni dello schema GraphQL di Fabric e convalida la compatibilità tra ambienti

Scegliere l'introspezione quando è necessario eseguire query sulle informazioni sullo schema a livello di codice in fase di esecuzione, ad esempio abilitare gli strumenti di sviluppo, abilitare gli agenti di intelligenza artificiale o implementare funzionalità client dinamiche. Scegliere l'esportazione dello schema quando è necessario un file di schema completo per l'uso offline, il controllo della versione, l'integrazione del gateway API o la condivisione con i team esterni.

  • Introspezione: eseguire una query sullo schema a livello di codice usando il sistema di introspezione GraphQL, che fa parte dello standard GraphQL. Le query di introspezione consentono di individuare tipi, campi e relazioni in modo dinamico e supportano molti strumenti di sviluppo GraphQL.

  • Esportazione dello schema: scaricare un file SDL completo (GraphQL Schema Definition Language) che contiene l'intera definizione dello schema per l'uso offline, la condivisione o l'integrazione degli strumenti.

Introspezione

Per impostazione predefinita, l'introspezione è disabilitata nell'API per gli elementi GraphQL. Questa impostazione può essere attivata o disattivata solo dagli amministratori dell'area di lavoro. Tutti gli altri utenti vedranno un cursore disabilitato.

Per abilitare l'introspezione:

  1. Selezionare l'icona a forma di ingranaggio Impostazioni API nel menu in alto.

    Screenshot che mostra la barra del portale con il pulsante a forma di ingranaggio delle impostazioni.

  2. Nel riquadro di spostamento a sinistra selezionare la pagina Introspection .

    Screenshot che mostra il cursore delle impostazioni di introspezione.

  3. Selezionare l'interruttore per abilitare l'introspezione. L'abilitazione dell'introspezione espone le informazioni sullo schema a tutti gli utenti con accesso all'endpoint API.

  4. Viene visualizzata una finestra di dialogo di conferma. Selezionare Conferma per abilitare l'introspezione o Annulla per lasciarla disabilitata.

    Screenshot che mostra la finestra di dialogo per confermare l'abilitazione dell'introspezione.

Query di introspezione: esempio

Di seguito è riportato un rapido esempio di una query di introspezione per recuperare i tipi disponibili dallo schema:

  1. Creare una nuova query nell'editor GraphQL. Selezionare l'icona con il segno più + accanto alle schede esistenti per aprire una nuova scheda query.

    Screenshot che mostra il pulsante della nuova query nell'editor GraphQL.

  2. Immettere la query di introspezione seguente nell'editor:

    query {
    __schema {
        types{
            name
        }
    }
}

  3. Selezionare il pulsante Esegui per eseguire la query.

  4. Nel riquadro dei risultati viene visualizzato un elenco di tutti i tipi definiti nello schema.

    Screenshot che mostra l'esempio di query di introspezione.

Le query di introspezione possono restituire grandi quantità di informazioni. È possibile limitare l'ambito della tua query specificando maggiormente la richiesta di introspezione. Ad esempio, invece di eseguire query su tutti i tipi, è possibile eseguire query su un tipo specifico:

query {
    __type(name: "ProductCategory") {
        name
        kind
        fields {
            name
            type {
                name
            }
        }
    }
}

L'esecuzione della query restituisce informazioni dettagliate sul ProductCategory tipo:

{
  "data": {
    "__type": {
      "name": "ProductCategory",
      "kind": "OBJECT",
      "fields": [
        {
          "name": "ProductCategoryID",
          "type": {
            "name": null
          }
        },
        {
          "name": "ParentProductCategoryID",
          "type": {
            "name": "Int"
          }
        },
        {
          "name": "Name",
          "type": {
            "name": "String"
          }
        },
        {
          "name": "rowguid",
          "type": {
            "name": null
          }
        },
        {
          "name": "ModifiedDate",
          "type": {
            "name": null
          }
        }
      ]
    }
  }
}

I modelli di filtro comuni durante l'elaborazione dei risultati dell'introspezione includono:

  • Esclusione dei tipi che iniziano con caratteri di sottolineatura doppia (__), che sono tipi di sistema GraphQL
  • Inclusione di tipi che iniziano con prefissi specifici, ad esempio ProductCategory

Questi esempi illustrano la sintassi di introspezione GraphQL standard che funziona in qualsiasi implementazione di GraphQL. Questa panoramica illustra i modelli di introspezione di base, per informazioni dettagliate sul sistema di introspezione, sulle tecniche di query avanzate e sulle funzionalità aggiuntive, vedere la documentazione ufficiale di GraphQL Foundation sull'introspezione.

Esportare lo schema

Quando è necessaria una copia completa e offline della definizione dello schema, usare la funzionalità di esportazione dello schema direttamente dal portale di Fabric. Aprire l'API per GraphQL e selezionare Esporta schema dalla barra degli strumenti. Il browser scarica un file SDL (Schema Definition Language) contenente la definizione completa dello schema.

Screenshot che mostra il pulsante esporta schema.

Informazioni sul file SDL

Il file esportato usa il linguaggio SDL (Schema Definition Language) di GraphQL, un formato leggibile che definisce i tipi, i campi e le relazioni dell'API. Il file SDL include:

  • Tipi di oggetto che rappresentano le entità di dati con i relativi campi
  • Operazioni di query che definiscono come recuperare i dati
  • Operazioni di mutazione per la creazione, l'aggiornamento o l'eliminazione di dati
  • Argomenti di campo che specificano i parametri di input e i relativi tipi
  • Descrizioni dei tipi che forniscono la documentazione per ogni elemento

È possibile aprire il file SDL in qualsiasi editor di testo per esaminare la struttura dello schema. Ciò è particolarmente utile per comprendere la superficie API completa prima di integrarla nelle applicazioni.

Uso dello schema esportato

I casi d'uso comuni per il file SDL esportato includono:

  • Integrazione del gateway API: importare in Gestione API di Azure per aggiungere autenticazione, limitazione del traffico e caching
  • Configurazione dell'ambiente di sviluppo: configurare IntelliSense in Visual Studio Code per il completamento automatico e la convalida
  • Controllo della versione: eseguire il commit in Git o in altri sistemi di controllo del codice sorgente per tenere traccia dell'evoluzione dello schema nel tempo
  • Collaborazione tra team: condividere con partner esterni o team di sviluppo che devono comprendere la struttura dell'API
  • Generazione di codice: Creare client a tipi sicuri usando i generatori di codice GraphQL in TypeScript, C#, Java o altri linguaggi
  • Documentazione: Generare la documentazione di riferimento dell'API usando strumenti come GraphQL Voyager o GraphQL Markdown

A differenza delle query di introspezione, l'esportazione dello schema non richiede l'abilitazione dell'introspezione e funziona indipendentemente dalle impostazioni di introspezione dell'API. In questo modo è possibile accedere alla definizione dello schema in modo affidabile per scopi amministrativi e di sviluppo.

Gestione delle modifiche dello schema

Gli schemi GraphQL possono evolversi nel tempo man mano che si aggiungono nuovi tipi, campi o funzionalità all'API. Quando lo schema cambia, i file SDL esportati diventano obsoleti. Prendere in considerazione queste procedure:

  • Rieseguire l'esportazione dopo le modifiche: scaricare un nuovo file SDL ogni volta che si modifica lo schema DELL'API in Fabric. Le modifiche dello schema includono l'aggiunta di origini dati, la modifica di tipi esposti o l'aggiornamento delle definizioni dei campi.
  • Controllo della versione: eseguire il commit di ogni schema esportato nel sistema di controllo del codice sorgente con messaggi di commit descrittivi. In questo modo viene creato un audit trail dell'evoluzione dello schema e viene abilitato il rollback, se necessario.
  • Comunicazione: se i team esterni o le applicazioni dipendono dallo schema, notificare loro modifiche significative. Mentre GraphQL supporta modifiche aggiuntive senza interrompere le query esistenti, la rimozione o la ridenominazione dei campi può influire su client.
  • Automazione: per le pipeline CI/CD, è consigliabile automatizzare le esportazioni dello schema come parte del processo di distribuzione per garantire che la documentazione e gli strumenti rimangano sincronizzati con l'API.

La persona responsabile della modifica dello schema API (in genere un data engineer o sviluppatore di API) deve esportare e versionare lo schema aggiornato per mantenere la coerenza con l'API Fabric e i sistemi esterni che dipendono da esso.

Contenuti correlati

  • Last updated on