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, 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:

Disponibilità

• Le API GraphQL sono supportate in tutti i livelli di servizio di Gestione API
• Attualmente le API GraphQL sintetiche non sono 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 rispetto alle esigenze della pagina di cui viene eseguito il rendering
• 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 richiesta singola 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 le 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 analogo a un'operazione GET in REST

• Mutazione: modifica i dati lato server, in modo analogo a un'operazione PUT o PATCH in REST

• Sottoscrizione: consente di inviare notifiche in tempo reale ai client con sottoscrizione sulle modifiche 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:

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.

Passaggi successivi

• Importare un'API GraphQL
• Importare uno schema di GraphQL e configurare resolver di campo