Panoramica delle API GraphQL in Gestione API di Azure

Articolo
05/07/2024

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:

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

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:

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.

Condividi tramite