Condividi tramite

Panoramica delle API GraphQL in Gestione API di Azure

SI APPLICA A: Tutti i livelli di Gestione API

È possibile usare Gestione API per gestire le API GraphQL, che sono API basate sul linguaggio di query GraphQL. GraphQL fornisce una descrizione completa e comprensibile dei dati in un'API, consentendo ai client di recuperare in modo efficiente esattamente i dati che sono necessari. Altre informazioni su GraphQL.

Gestione API consente di importare, gestire, proteggere, testare, pubblicare e monitorare le API GraphQL. È possibile scegliere uno dei due modelli API:

GraphQL pass-through GraphQL sint.
▪️ API pass-through all'endpoint di servizio GraphQL esistente

▪️ Supporto per query GraphQL, mutazioni e sottoscrizioni		 ▪️ API basata su uno schema GraphQL personalizzato

▪️ Supporto per query GraphQL, mutazioni e sottoscrizioni

▪️ Configurare resolver personalizzati, ad esempio in origini dati HTTP

▪️ Sviluppare schemi GraphQL e client basati su GraphQL durante l'utilizzo dei dati dalle API legacy

▪️ Le sottoscrizioni sintetiche non richiedono resolver. Vedere criteri di pubblicazione-evento .

Disponibilità

  • Le API GraphQL sono supportate in tutti i livelli di servizio Gestione API.
  • Le API GraphQL sintetiche non sono attualmente supportate nelle aree di lavoro di Gestione API.
  • Il supporto per le sottoscrizioni GraphQL nelle API GraphQL sintetiche è attualmente in anteprima e non è disponibile nel livello a consumo.

Che cos'è GraphQL?

GraphQL è un linguaggio di query open source per le API che costituisce uno standard del settore. A differenza delle API di tipo REST progettate per le azioni sulle risorse, le API GraphQL supportano un set più ampio di casi d'uso e si concentrano su tipi di dati, schemi e query.

La specifica GraphQL risolve in modo esplicito i problemi comuni riscontrati dalle app Web client che si basano sulle API REST:

  • Può essere necessario un numero elevato di richieste per soddisfare le esigenze di dati per una singola pagina.
  • Le API REST spesso restituiscono più dati del necessario per il rendering della pagina.
  • L'app client deve eseguire il polling per ottenere nuove informazioni.

Usando un'API GraphQL, l'app client può specificare i dati necessari per eseguire il rendering di una pagina in un documento di query inviato come singola richiesta a un servizio GraphQL. Un'app client può anche abbonarsi agli aggiornamenti dei dati inseriti dal servizio GraphQL in tempo reale.

Schema e tipi

In Gestione API aggiungere un'API GraphQL da uno schema GraphQL, recuperata da un endpoint dell'API GraphQL back-end o caricata dall'utente. Uno schema GraphQL descrive:

  • Tipi di oggetto dati e campi che i client possono richiedere da un'API GraphQL.
  • Tipi di operazione consentiti nei dati, ad esempio query.
  • Altri tipi, ad esempio unioni e interfacce, che offrono flessibilità e controllo aggiuntivi sui dati.

Ad esempio, uno schema GraphQL di base per i dati utente e una query per tutti gli utenti potrebbe avere un aspetto simile al seguente:

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}

Tipi di operazione

Gestione API supporta i tipi di operazione seguenti negli schemi GraphQL. Per altre informazioni su questi tipi di operazione, vedere la specifica GraphQL.

  • Query: recupera i dati, in modo simile a un'operazione GET in REST.

  • Mutazione: modifica i dati lato server, come un'operazione PUT o PATCH in REST.

  • Sottoscrizione: consente di inviare notifiche ai client sottoscritti in tempo reale sulle modifiche apportate ai dati nel servizio GraphQL.

    Ad esempio, quando i dati vengono modificati tramite una mutazione GraphQL, i client con sottoscrizione potrebbero ricevere automaticamente una notifica sulla modifica.

    Importante

    Gestione API supporta sottoscrizioni implementate mediante il protocollo WebSocket graphql-ws. Le query e le mutazioni non sono supportate su WebSocket.

Altri tipi

Gestione API supporta i tipi di unione e interfaccia negli schemi GraphQL.

Resolver

I resolver si occupano del mapping dello schema GraphQL ai dati back-end, producendo i dati per ogni campo in un tipo di oggetto. L'origine dati può essere un'API, un database o un altro servizio. Ad esempio, una funzione resolver sarà responsabile della restituzione dei dati per la query users nell'esempio precedente.

In Gestione API è possibile creare un resolver per eseguire il mapping di un campo in un tipo di oggetto a un'origine dati back-end. È possibile configurare i resolver per i campi negli schemi API GraphQL sintetici, ma è anche possibile configurarli per eseguire l'override dei resolver di campi predefiniti usati dalle API GraphQL pass-through.

Gestione API supporta attualmente i resolver basati su API HTTP, Cosmos DB e origini dati SQL di Azure per restituire i dati per i campi in uno schema GraphQL. Ogni resolver viene configurato usando criteri personalizzati per connettersi all'origine dati e recuperare i dati:

Origine dati Criteri del risolver
Origine dati basata su HTTP (API REST o SOAP) http-data-source
Database Cosmos DB cosmosdb-data-source
Database SQL di Azure sql-data-source

Ad esempio, un resolver basato su API HTTP per la query users precedente potrebbe eseguire il mapping a un'operazione GET in un'API REST back-end:

<http-data-source>
    <http-request>
        <set-method>GET</set-method>
        <set-url>https://myapi.contoso.com/api/users</set-url>
    </http-request>
</http-data-source>

Per altre informazioni sulla configurazione di un resolver, vedere Configurare un resolver GraphQL.

Gestire le API GraphQL

  • Proteggere le API GraphQL applicando criteri di controllo di accesso esistenti e criteri di convalida di GraphQL per la protezione da attacchi specifici per GraphQL.
  • Esplorare lo schema GraphQL ed eseguire query di test nelle API GraphQL nel portale per sviluppatori di Azure e nel portale per sviluppatori.

Contenuti correlati

  • Last updated on