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:

• 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

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.

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!
}

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.

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

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.

• 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.

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