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

Статья
05/05/2024

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

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

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

GraphQL со сквозной передачей	Синтетический GraphQL
▪️ Сквозной API в существующую конечную точку службы GraphQL ▪️ Поддержка запросов GraphQL, мутаций и подписок	▪️ API на основе пользовательской схемы GraphQL ▪️ Поддержка запросов GraphQL, мутаций и подписок ▪️ Настройка пользовательских сопоставителей, например для источников данных HTTP ▪️ Разработка схем GraphQL и клиентов на основе GraphQL при использовании данных из устаревших API

GraphQL со сквозной передачей

Синтетический GraphQL

▪️ Сквозной API в существующую конечную точку службы GraphQL

▪️ Поддержка запросов GraphQL, мутаций и подписок

▪️ API на основе пользовательской схемы GraphQL

▪️ Поддержка запросов GraphQL, мутаций и подписок

▪️ Настройка пользовательских сопоставителей, например для источников данных HTTP

▪️ Разработка схем GraphQL и клиентов на основе GraphQL при использовании данных из устаревших API

Availability

API GraphQL поддерживаются во всех уровнях служб Управление API
Искусственные API GraphQL в настоящее время не поддерживаются в Управление API рабочих областях
Поддержка подписок GraphQL в искусственных API GraphQL в настоящее время доступна в предварительной версии и недоступна на уровне потребления

Что такое GraphQL?

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

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

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

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

Схема и типы

В Управление API добавьте API GraphQL из схемы GraphQL, извлекаемую из конечной точки API GraphQL серверной части или отправленную вами. Схема 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.

Распознаватели

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

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

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

Источник данных	Политика сопоставителя
Источник данных на основе HTTP (REST или SOAP API)	http-data-source
Базы данных Azure Cosmos DB.	cosmosdb-data-source
База данных SQL Azure	sql-data-source

Например, сопоставитель API HTTP для предыдущего users запроса может сопоставить с GET операцией в серверном 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 и разработчиков.

Поделиться через