Sdílet prostřednictvím

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

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
▪️ Průchozí API pro existující koncový bod 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 resolverů, například pro HTTP datové zdroje

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

▪️ Syntetická předplatná nevyžadují řešitele. Viz zásady publikování událostí.

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:

  • Je potřeba velký počet požadavků k naplnění datových potřeb jedné stránky.
  • 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.

Schéma a typy

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
  • Další typy, jako jsou sjednocení a rozhraní, které poskytují větší flexibilitu a kontrolu nad daty

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

Typy operace

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čítá data podobně jako GET operace 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 mutace nejsou podporovány přes WebSocket.

Další typy

API Management podporuje typy union a rozhraní ve schématech GraphQL.

Řešitelé

Resolvery se starají o mapování schématu GraphQL na backendová data, čímž 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 resolver pro mapování pole v typu objektu na datový zdroj backendu. Konfigurujete resolvery pro pole v syntetických schématech rozhraní GraphQL API, ale můžete je také nakonfigurovat tak, aby přetížily výchozí resolvery polí používané průchozymi rozhraními GraphQL API.

SLUŽBA API Management v současné době podporuje resolvery 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 řešitele
Zdroj dat založený na HTTP (REST nebo SOAP API) zdroj-dat-http
Databázi Cosmos DB cosmosdb-data-source
Databáze Azure SQL zdroj dat SQL

Například resolver používající HTTP API pro předchozí users dotaz může mapovat na GET operaci v backendové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.

Související obsah