Panoramica delle API GraphQL in Azure Gestione API

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

È possibile usare Gestione API per gestire le API GraphQL: 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 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 seguenti:

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 Gestione API
  • Le API GraphQL sintetiche non sono attualmente supportate nelle aree di lavoro Gestione API
  • Il supporto per le sottoscrizioni GraphQL nelle API GraphQL sintetiche è attualmente in anteprima e non è disponibile nel livello Consumo

Che cos'è GraphQL?

GraphQL è un linguaggio di query open source standard per le API. 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 concentrarsi 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 singola richiesta a un servizio GraphQL. Un'app client può anche sottoscrivere gli aggiornamenti dei dati inseriti dal servizio GraphQL in tempo reale.

Tipi di schema e operazioni

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

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, simili a un'operazione PUT o PATCH in REST

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

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

Importante

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

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 users query nell'esempio precedente.

In Gestione API è possibile creare un sistema di risoluzione 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 sistema di risoluzione viene configurato usando criteri personalizzati per connettersi all'origine dati e recuperare i dati:

Origine dati Criterio del sistema di risoluzione
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 sistema di risoluzione basato su API HTTP per la query precedente users 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 sistema di risoluzione, vedere Configurare un resolver GraphQL.

Gestire le API GraphQL

  • Proteggere le API GraphQL applicando criteri di controllo di accesso esistenti e criteri di convalida GraphQL per proteggere e proteggere da attacchi specifici di GraphQL.
  • Esplorare lo schema GraphQL ed eseguire query di test sulle API GraphQL nei portali di Azure e per sviluppatori.

Passaggi successivi