Översikt över GraphQL-API:er i Azure API Management

  • Artikel

GÄLLER FÖR: Alla API Management-nivåer

Du kan använda API Management för att hantera GraphQL-API:er – API:er baserat på GraphQL-frågespråket. GraphQL ger en fullständig och begriplig beskrivning av data i ett API, vilket ger klienterna möjlighet att effektivt hämta exakt de data de behöver. Läs mer om GraphQL

API Management hjälper dig att importera, hantera, skydda, testa, publicera och övervaka GraphQL-API:er. Du kan välja en av två API-modeller:

GraphQL för direktströmning Syntetisk GraphQL
▪️ Direkt-API till befintlig GraphQL-tjänstslutpunkt

▪️ Stöd för GraphQL-frågor, mutationer och prenumerationer		 ▪️ API baserat på ett anpassat GraphQL-schema

▪️ Stöd för GraphQL-frågor, mutationer och prenumerationer

▪️ Konfigurera anpassade matchare, till exempel till HTTP-datakällor

▪️ Utveckla GraphQL-scheman och GraphQL-baserade klienter samtidigt som data från äldre API:er används

Tillgänglighet

  • GraphQL-API:er stöds på alla API Management-tjänstnivåer
  • Syntetiska GraphQL-API:er stöds för närvarande inte i API Management-arbetsytor
  • Stöd för GraphQL-prenumerationer i syntetiska GraphQL-API:er är för närvarande i förhandsversion och är inte tillgängligt på förbrukningsnivån

Vad är GraphQL?

GraphQL är ett frågespråk med öppen källkod och branschstandard för API:er. Till skillnad från API:er i REST-format som utformats kring åtgärder över resurser stöder GraphQL-API:er en bredare uppsättning användningsfall och fokuserar på datatyper, scheman och frågor.

GraphQL-specifikationen löser uttryckligen vanliga problem som uppstår i klientwebbappar som förlitar sig på REST-API:er:

  • Det kan krävas ett stort antal begäranden för att uppfylla databehoven för en enda sida
  • REST-API:er returnerar ofta mer data än vad som behövs av sidan som återges
  • Klientappen måste avsökas för att få ny information

Med hjälp av ett GraphQL-API kan klientappen ange de data de behöver för att återge en sida i ett frågedokument som skickas som en enda begäran till en GraphQL-tjänst. En klientapp kan också prenumerera på datauppdateringar som skickas från GraphQL-tjänsten i realtid.

Schema- och åtgärdstyper

I API Management lägger du till ett GraphQL-API från ett GraphQL-schema, antingen hämtat från en GraphQL API-slutpunkt för serverdelen eller uppladdat av dig. Ett GraphQL-schema beskriver:

  • Dataobjekttyper och fält som klienter kan begära från ett GraphQL-API
  • Åtgärdstyper som tillåts för data, till exempel frågor

Ett grundläggande GraphQL-schema för användardata och en fråga för alla användare kan till exempel se ut så här:

type Query {
    users: [User]
}

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

API Management stöder följande åtgärdstyper i GraphQL-scheman. Mer information om dessa åtgärdstyper finns i GraphQL-specifikationen.

  • Fråga – Hämtar data som liknar en GET åtgärd i REST

  • Mutation – Ändrar data på serversidan, liknande en eller PATCH -PUTåtgärd i REST

  • Prenumeration – Aktiverar avisering av prenumerationsklienter i realtid om ändringar i data i GraphQL-tjänsten

    När data till exempel ändras via en GraphQL-mutation kan prenumerationsklienter meddelas automatiskt om ändringen.

Viktigt!

API Management stöder prenumerationer som implementeras med hjälp av WebSocket-protokollet graphql-ws . Frågor och mutationer stöds inte via WebSocket.

Matchare

Matchare tar hand om att mappa GraphQL-schemat till serverdelsdata och producerar data för varje fält i en objekttyp. Datakällan kan vara ett API, en databas eller en annan tjänst. En lösningsfunktion skulle till exempel vara ansvarig för att returnera data för users frågan i föregående exempel.

I API Management kan du skapa en matchare för att mappa ett fält i en objekttyp till en serverdelsdatakälla. Du konfigurerar matchare för fält i syntetiska GraphQL API-scheman, men du kan också konfigurera dem så att de åsidosätter de standardfältlösare som används av GraphQL-API:er för direktströmning.

API Management stöder för närvarande matchare baserat på HTTP API, Cosmos DB och Azure SQL-datakällor för att returnera data för fält i ett GraphQL-schema. Varje matchare konfigureras med en anpassad princip för att ansluta till datakällan och hämta data:

Data source Lösningsprincip
HTTP-baserad datakälla (REST eller SOAP API) http-data-source
Cosmos DB-databas cosmosdb-data-source
Azure SQL-databas sql-data-source

Till exempel kan en HTTP API-baserad matchare för föregående fråga mappas users till en GET åtgärd i ett REST-API för serverdelen:

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

Mer information om hur du konfigurerar en lösning finns i Konfigurera en GraphQL-matchare.

Hantera GraphQL-API:er

  • Skydda GraphQL-API:er genom att använda både befintliga principer för åtkomstkontroll och en GraphQL-valideringsprincip för att skydda mot GraphQL-specifika attacker.
  • Utforska GraphQL-schemat och kör testfrågor mot GraphQL-API:erna i Azure- och utvecklarportalerna.

Nästa steg