Omówienie interfejsów API graphQL w usłudze Azure API Management

Artykuł
05/05/2024

DOTYCZY: Wszystkie warstwy usługi API Management

Usługa API Management umożliwia zarządzanie interfejsami API GraphQL — interfejsami API opartymi na języku zapytań GraphQL. Narzędzie GraphQL udostępnia pełny i zrozumiały opis danych w interfejsie API, zapewniając klientom możliwość wydajnego pobierania dokładnie potrzebnych danych. Dowiedz się więcej o języku GraphQL

Usługa API Management ułatwia importowanie, ochronę, testowanie, publikowanie i monitorowanie interfejsów API graphQL oraz zarządzanie nimi. Możesz wybrać jeden z dwóch modeli interfejsu API:

Przekazywanie GraphQL	Syntetyczny GraphQL
▪️ Przekazywanie interfejsu API do istniejącego punktu końcowego usługi GraphQL ▪️ Obsługa zapytań GraphQL, mutacji i subskrypcji	▪️ Interfejs API oparty na niestandardowym schemacie GraphQL ▪️ Obsługa zapytań GraphQL, mutacji i subskrypcji ▪️ Konfigurowanie niestandardowych narzędzi rozpoznawania nazw, na przykład do źródeł danych HTTP ▪️ Opracowywanie schematów GraphQL i klientów opartych na języku GraphQL podczas korzystania z danych ze starszych interfejsów API

Dostępność

Interfejsy API graphQL są obsługiwane we wszystkich warstwach usługi API Management
Syntetyczne interfejsy API graphQL nie są obecnie obsługiwane w obszarach roboczych usługi API Management
Obsługa subskrypcji graphQL w syntetycznych interfejsach API graphQL jest obecnie dostępna w wersji zapoznawczej i nie jest dostępna w warstwie Zużycie

Co to jest GraphQL?

GraphQL to standardowy język zapytań typu open source dla interfejsów API. W przeciwieństwie do interfejsów API w stylu REST zaprojektowanych wokół akcji dotyczących zasobów, interfejsy API GraphQL obsługują szerszy zestaw przypadków użycia i koncentrują się na typach danych, schematach i zapytaniach.

Specyfikacja graphQL jawnie rozwiązuje typowe problemy występujące przez aplikacje internetowe klienta, które korzystają z interfejsów API REST:

Może upłynąć duża liczba żądań, aby spełnić wymagania dotyczące danych dla jednej strony
Interfejsy API REST często zwracają więcej danych niż jest to wymagane przez renderowaną stronę
Aplikacja kliencka musi sondować, aby uzyskać nowe informacje

Za pomocą interfejsu API graphQL aplikacja kliencka może określić dane, które muszą renderować stronę w dokumencie zapytania, który jest wysyłany jako pojedyncze żądanie do usługi GraphQL. Aplikacja kliencka może również subskrybować aktualizacje danych wypychane z usługi GraphQL w czasie rzeczywistym.

Schemat i typy

W usłudze API Management dodaj interfejs API GraphQL ze schematu GraphQL pobranego z punktu końcowego interfejsu API graphQL zaplecza lub przekazanego przez Ciebie. Schemat GraphQL opisuje:

Typy obiektów danych i pola, których klienci mogą żądać z poziomu interfejsu API GraphQL
Dozwolone typy operacji na danych, takie jak zapytania
Inne typy, takie jak związki i interfejsy, zapewniają dodatkową elastyczność i kontrolę nad danymi

Na przykład podstawowy schemat graphQL dla danych użytkownika i zapytanie dla wszystkich użytkowników może wyglądać następująco:

type Query {
    users: [User]
}

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

Rodzaje operacji

Usługa API Management obsługuje następujące typy operacji w schematach GraphQL. Aby uzyskać więcej informacji na temat tych typów operacji, zobacz specyfikację GraphQL.

Zapytanie — pobiera dane, podobnie jak operacja w interfejsie GET REST
Mutacja — modyfikuje dane po stronie serwera, podobne do operacji lub PATCH w architekturze PUT REST
Subskrypcja — umożliwia powiadamianie subskrybowanych klientów w czasie rzeczywistym o zmianach danych w usłudze GraphQL

Na przykład gdy dane są modyfikowane za pośrednictwem mutacji GraphQL, subskrybowani klienci mogą być automatycznie powiadamiani o zmianie.

Ważne

Usługa API Management obsługuje subskrypcje implementowane przy użyciu protokołu WebSocket graphql-ws . Zapytania i mutacje nie są obsługiwane za pośrednictwem protokołu WebSocket.

Inne typy

Usługa API Management obsługuje typy unii i interfejsów w schematach GraphQL.

Programy rozpoznawania nazw

Narzędzia rozpoznawania nazw dbają o mapowanie schematu GraphQL na dane zaplecza, generując dane dla każdego pola w typie obiektu. Źródłem danych może być interfejs API, baza danych lub inna usługa. Na przykład funkcja rozpoznawania nazw będzie odpowiedzialna za zwracanie danych dla users zapytania w poprzednim przykładzie.

W usłudze API Management można utworzyć program rozpoznawania nazw, aby zamapować pole w typie obiektu na źródło danych zaplecza. Można skonfigurować narzędzia rozpoznawania pól w syntetycznych schematach interfejsu API GraphQL, ale można je również skonfigurować tak, aby zastąpić domyślne narzędzia rozpoznawania pól używane przez interfejsy API grafql przekazywania.

Usługa API Management obecnie obsługuje programy rozpoznawania na podstawie interfejsu API HTTP, usługi Cosmos DB i źródeł danych Usługi Azure SQL w celu zwrócenia danych dla pól w schemacie GraphQL. Każdy program rozpoznawania nazw jest skonfigurowany przy użyciu dostosowanych zasad w celu nawiązania połączenia ze źródłem danych i pobrania danych:

Źródło danych	Zasady rozpoznawania
Źródło danych oparte na protokole HTTP (interfejs API REST lub SOAP)	http-data-source
Baza danych Cosmos DB	cosmosdb-data-source
Azure SQL database	sql-data-source

Na przykład program rozpoznawania interfejsu API HTTP dla powyższego users zapytania może mapować na operację GET w interfejsie API REST zaplecza:

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

Aby uzyskać więcej informacji na temat konfigurowania narzędzia rozpoznawania nazw, zobacz Konfigurowanie programu GraphQL resolver.

Zarządzanie interfejsami API graphQL

Zabezpieczanie interfejsów API języka GraphQL przez zastosowanie zarówno istniejących zasad kontroli dostępu, jak i zasad weryfikacji graphQL w celu zabezpieczenia i ochrony przed atakami specyficznymi dla języka GraphQL.
Zapoznaj się ze schematem GraphQL i uruchom zapytania testowe względem interfejsów API GraphQL w portalach platformy Azure i deweloperów.

Share via