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

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

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

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

Доступность

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

Что такое GraphQL?

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

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

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

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

Схема и типы

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

Resolvers

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

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

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

Например, сопоставитель 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 и разработчиков.

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

• Импортируйте API GraphQL
• Добавление искусственного API GraphQL и настройка сопоставителей полей