Обзор GraphQL API в Управлении API Azure

ОБЛАСТЬ ПРИМЕНЕНИЯ: Все уровни управления API

Вы можете использовать Управление API для управления API GraphQL — API на основе языка запросов GraphQL. GraphQL предоставляет полное и понятное описание данных в API, что дает клиентам возможность эффективно извлекать нужные данные. Дополнительные сведения о GraphQL

Управление API помогает импортировать, управлять, защищать, тестировать, публиковать и отслеживать API GraphQL. Вы можете выбрать одну из двух моделей API:

Доступность

• GraphQL APIs are supported in all API Management service tiers
• Синтетические API GraphQL в настоящее время не поддерживаются в рабочих областях Управления API
• Support for GraphQL subscriptions in synthetic GraphQL APIs is currently in preview and isn't available in the Consumption tier

Что такое GraphQL?

GraphQL — это стандартный в отрасли язык запросов с открытым исходным кодом. В отличие от API в стиле REST, разработанных вокруг действий над ресурсами, API GraphQL поддерживают более широкий спектр вариантов использования и сосредоточиваются на типах данных, схемах и запросах.

Спецификация GraphQL явно решает распространенные проблемы, с которыми сталкиваются клиентские веб-приложения, использующие REST API:

• Для выполнения потребностей данных на одной странице может потребоваться большое количество запросов.
• REST API часто возвращают больше данных, чем нужно для визуализации страницы.
• Клиентское приложение должно провести опрос, чтобы получить новые сведения

С помощью API GraphQL клиентское приложение может указать данные, необходимые для отрисовки страницы в документе запроса, который отправляется в виде одного запроса в службу GraphQL. Клиентское приложение также может подписаться на обновления данных, отправленные из службы GraphQL в режиме реального времени.

Схема и типы

In API Management, add a GraphQL API from a GraphQL schema, either retrieved from a backend GraphQL API endpoint or uploaded by you. Схема GraphQL описывает:

• Типы объектов данных и поля, которые клиенты могут запрашивать из API GraphQL
• Типы операций, разрешенные для данных, например запросы
• Другие типы, такие как объединения и интерфейсы, которые обеспечивают дополнительную гибкость и контроль над данными

Например, базовая схема GraphQL для пользовательских данных и запрос для всех пользователей может выглядеть следующим образом:

type Query {
    users: [User]
}

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

Типы операций

Управление API поддерживает следующие типы операций в схемах GraphQL. Дополнительные сведения об этих типах операций см. в спецификации GraphQL.

• Запрос — получение данных, аналогичных GET операции в REST

• Мутация — изменяет данные на стороне сервера, аналогичные PUT операции или PATCH операции в REST

• Подписка . Включает уведомление клиентов, подписанных в режиме реального времени об изменениях данных в службе GraphQL

  Например, когда данные изменяются с помощью изменения GraphQL, подписанные клиенты могут автоматически получать уведомления об изменении.

  Внимание

  Управление API поддерживает подписки, реализованные с помощью протокола Graphql-ws WebSocket. Запросы и изменения не поддерживаются через WebSocket.

Другие типы

Управление API поддерживает типы объединения и интерфейса в схемах GraphQL.

Resolvers

Сопоставители заботятся о сопоставлении схемы GraphQL с внутренними данными, создавая данные для каждого поля в типе объекта. Источник данных может быть API, база данных или другая служба. Например, функция сопоставителя будет отвечать за возврат данных для users запроса в предыдущем примере.

In API Management, you can create a resolver to map a field in an object type to a backend data source. You configure resolvers for fields in synthetic GraphQL API schemas, but you can also configure them to override the default field resolvers used by pass-through GraphQL APIs.

Управление API в настоящее время поддерживает резолверы, которые используют HTTP API, Cosmos DB и источники данных Azure SQL для возврата данных полей в схеме GraphQL. Каждый сопоставитель настраивается с помощью настраиваемой политики для подключения к источнику данных и получения данных:

For example, an HTTP API-based resolver for the preceding users query might map to a GET operation in a backend 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>

Дополнительные сведения о настройке сопоставителя см. в разделе "Настройка сопоставителя GraphQL".

Управление API GraphQL

• Защитить API GraphQL путем применения существующих политик управления доступом и политики проверки GraphQL для защиты от атак, направленных на GraphQL.
• Изучите схему GraphQL и выполните тестовые запросы к API GraphQL на порталах Azure и разработчиков.

Связанный контент

• Import a GraphQL API
• Импорт схемы GraphQL и настройка сопоставителей полей