Přehled rozhraní GraphQL API ve službě Azure API Management

  • Článek

PLATÍ PRO: Všechny úrovně služby API Management

Službu API Management můžete použít ke správě rozhraní GraphQL API – rozhraní API na základě dotazovacího jazyka GraphQL. GraphQL poskytuje úplný a srozumitelný popis dat v rozhraní API a poskytuje klientům možnost efektivně načítat přesně potřebná data. Další informace o GraphQL

API Management pomáhá importovat, spravovat, chránit, testovat, publikovat a monitorovat rozhraní GraphQL API. Můžete zvolit jeden ze dvou modelů rozhraní API:

Průchozí GraphQL Syntetický GraphQL
▪️ Předávací rozhraní API do existujícího koncového bodu služby GraphQL

▪️ Podpora dotazů GraphQL, mutací a předplatných		 ▪️ Rozhraní API založené na vlastním schématu GraphQL

▪️ Podpora dotazů GraphQL, mutací a předplatných

▪️ Konfigurace vlastních překladačů, například pro zdroje dat HTTP

▪️ Vývoj schémat GraphQL a klientů založených na GraphQL při využívání dat ze starších rozhraní API

Dostupnost

  • Rozhraní GraphQL API se podporují ve všech úrovních služby API Management.
  • Syntetická rozhraní GRAPHQL API se v současné době nepodporují v pracovních prostorech služby API Management .
  • Podpora předplatných GraphQL v syntetických rozhraních GraphQL API je aktuálně ve verzi Preview a není dostupná na úrovni Consumption.

Co je GraphQL?

GraphQL je opensourcový standardní dotazovací jazyk pro rozhraní API. Na rozdíl od rozhraní REST API navržených pro akce nad prostředky podporují rozhraní GraphQL API širší sadu případů použití a zaměřují se na datové typy, schémata a dotazy.

Specifikace GraphQL explicitně řeší běžné problémy, ke kterým dochází u klientských webových aplikací, které spoléhají na rozhraní REST API:

  • Může trvat velký počet požadavků, aby splňovaly požadavky na data pro jednu stránku.
  • Rozhraní REST API často vrací více dat, než je potřeba při vykreslení stránky.
  • Klientská aplikace se musí dotazovat, aby získala nové informace.

Pomocí rozhraní GraphQL API může klientská aplikace zadat data, která potřebují k vykreslení stránky v dokumentu dotazu, který se odešle jako jeden požadavek do služby GraphQL. Klientská aplikace se může také přihlásit k odběru aktualizací dat nabízených ze služby GraphQL v reálném čase.

Typy schémat a operací

Ve službě API Management přidejte rozhraní GraphQL API ze schématu GraphQL buď načtené z back-endového koncového bodu rozhraní GraphQL API, nebo nahrané vámi. Schéma GraphQL popisuje:

  • Datové objekty a pole, která můžou klienti požadovat z rozhraní GraphQL API
  • Typy operací povolené u dat, jako jsou dotazy

Například základní schéma GraphQL pro uživatelská data a dotaz pro všechny uživatele může vypadat takto:

type Query {
    users: [User]
}

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

Služba API Management podporuje následující typy operací ve schématech GraphQL. Další informace o těchto typech operací najdete ve specifikaci GraphQL.

  • Dotaz – načte data podobná GET operaci v REST.

  • Mutování – upravuje data na straně serveru, podobně jako PUT operace nebo PATCH operace v REST.

  • Předplatné – Umožňuje upozorňovat předplacené klienty v reálném čase o změnách dat ve službě GraphQL.

    Když se například data upraví prostřednictvím mutaci GraphQL, můžou být přihlášení klienti k odběru automaticky upozorněni na změnu.

Důležité

API Management podporuje předplatná implementovaná pomocí protokolu Graphql-ws WebSocket. Dotazy a geny nejsou podporovány přes WebSocket.

Překladače

Překladače se starají o mapování schématu GraphQL na back-endová data a vytvářejí data pro každé pole v typu objektu. Zdrojem dat může být rozhraní API, databáze nebo jiná služba. Například funkce překladače odpovídá za vrácení dat pro users dotaz v předchozím příkladu.

Ve službě API Management můžete vytvořit překladač pro mapování pole v typu objektu na back-endový zdroj dat. Konfigurujete překladače pro pole v syntetických schématech rozhraní GraphQL API, ale můžete je také nakonfigurovat tak, aby přepsaly výchozí překladače polí používané předávacím rozhraním GraphQL API.

SLUŽBA API Management v současné době podporuje překladače založené na zdrojích dat HTTP API, Cosmos DB a Azure SQL, aby vrátila data pro pole ve schématu GraphQL. Každý překladač je nakonfigurovaný pomocí přizpůsobených zásad pro připojení ke zdroji dat a načtení dat:

Zdroj dat Zásady překladače
Zdroj dat založený na protokolu HTTP (ROZHRANÍ REST nebo SOAP API) http-data-source
Databázi Cosmos DB cosmosdb-data-source
Databáze Azure SQL sql-data-source

Například překladač založený na rozhraní API HTTP pro předchozí users dotaz může namapovat na GET operaci v back-endovém rozhraní REST API:

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

Další informace o nastavení překladače najdete v tématu Konfigurace překladače GraphQL.

Správa rozhraní GraphQL API

  • Zabezpečení rozhraní GraphQL API pomocí stávajících zásad řízení přístupu a zásad ověřování GraphQL k zabezpečení a ochraně před útoky specifickými pro GraphQL
  • Prozkoumejte schéma GraphQL a spusťte testovací dotazy na rozhraní GraphQL API na portálech Azure a pro vývojáře.

Další kroky