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

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:

Przechodzenie przez GraphQL

Syntetyczny GraphQL

▪️ API przejściowe 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 ▪️ Skonfiguruj niestandardowe resolvery, 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 ▪️ Syntetyczne subskrypcje nie wymagają resolverów. Zobacz politykę publikowania zdarzeń.

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 Zarządzania API
• Obsługa subskrypcji GraphQL w syntetycznych GraphQL API jest obecnie dostępna w wersji zapoznawczej i nie jest dostępna w warstwie Consumption

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ć, jakie dane są potrzebne do renderowania strony w dokumencie zapytania, który jest wysyłany jako pojedyncze żądanie do usługi GraphQL. Aplikacja kliencka może również subskrybować aktualizacje danych przekazywane 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 przesłanego przez użytkownika. 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, podobna do operacji PUT lub PATCH w architekturze 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 union i interface w schematach GraphQL.

Rozwiązujące systemy

Resolvers zajmują się mapowaniem schematu GraphQL na dane backendu, tworzą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 rozwiązująca będzie odpowiedzialna za zwracanie danych dla users zapytania w poprzednim przykładzie.

W ramach zarządzania API można utworzyć resolver, aby przyporządkować pole w typie obiektu na źródło danych backendu. Można skonfigurować resolvery pól w syntetycznych schematach API GraphQL, ale można je także skonfigurować tak, aby zastąpić domyślne resolvery pól używane przez przekazywane interfejsy API GraphQL.

Usługa API Management obecnie obsługuje mechanizmy rozwiązywania bazujące na HTTP API oraz źródłach danych Cosmos DB i 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 rozwiązywania
Źródło danych oparte na protokole HTTP (interfejs API REST lub SOAP)	źródło danych HTTP
Baza danych Cosmos DB	cosmosdb-data-source
Baza danych Azure SQL Database	źródło danych SQL

Na przykład resolver oparty na HTTP API dla powyższego users zapytania może mapować na operację GET w backendowym 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>

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.

Powiązana zawartość

• Import GraphQL API
• Importowanie schematu GraphQL i konfigurowanie rozpoznawania pól