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

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

С помощью Управления API для предоставления API GraphQL можно:

  • Добавить конечную точку GraphQL или схему GraphQL в качестве API с помощью портала Azure, Azure CLI или других средств Azure.
  • (Предварительная версия) Спроектировать или дополнить API GraphQL с использованием сведений из REST API или SOAP API с помощью сопоставителей HTTP для полей, определенных в схеме GraphQL.
  • Защитить API GraphQL путем применения существующих политик управления доступом и политики проверки GraphQL для защиты от атак, направленных на GraphQL.
  • Изучите схему и выполните тестовые запросы к API GraphQL на порталах Azure и разработчика.

Примечание

  • Один API GraphQL в Управлении API может быть сопоставлен только одной конечной точке в серверной части GraphQL.
  • Для API GraphQL требуется схема GraphQL из существующей конечной точки GraphQL или загруженная вами.
  • Управление API поддерживает типы операций "запрос", "изменение" и "подписка" в схемах GraphQL.
  • Подписки не поддерживаются на уровне служб Потребление.
  • Подписку необходимо реализовать с помощью протокола WebSocket graphql-ws. Запросы и изменения по протоколу WebSocket не поддерживаются.

Важно!

Настройка сопоставителей для запросов GraphQL сейчас доступна в предварительной версии. Эта функция не доступна на уровне служб Потребление и в локальном шлюзе.

Работая с этой статьей, вы узнаете о следующем.

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

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

Предварительные требования

  • Существующий экземпляр Управления API. Создайте его, если у вас его нет.
  • Допустимый файл схемы GraphQL с расширением .graphql.
  • Для этого сценария требуется конечная точка в серверной части GraphQL.

Перейдите к экземпляру службы управления API.

  1. На портале Azure найдите и выберите Службы управления API.

    Select API Management services

  2. На странице Службы Управления API выберите экземпляр Управления API.

    Select your API Management instance

Добавление схемы GraphQL

  1. В меню навигации сбоку выберите API в разделе API.

  2. В разделе Определение нового API щелкните значок Искусственный GraphQL.

    Screenshot of selecting Synthetic GraphQL icon from list of APIs.

  3. В открывшемся диалоговом окне выберите Полный и заполните обязательные поля формы.

    Screenshot of fields for creating a GraphQL API.

    Поле Description
    Отображаемое имя Это имя, под которым будет отображаться этот API GraphQL.
    имя; Необработанное имя API Graph. Оно заполняется автоматически при вводе отображаемого имени.
    Резервная конечная точка GraphQL В этом сценарии при необходимости введите URL-адрес с именем конечной точки API GraphQL. Управление API передает запросы GraphQL в эту конечную точку, если настраиваемый сопоставитель для поля не задан.
    Отправка файла схемы Выберите, чтобы просмотреть и отправить допустимый файл схемы GraphQL с расширением .graphql.
    Описание Добавьте описание API.
    Схема URL-адресов Выберите HTTP, HTTPS или Оба. Выбор по умолчанию: Both (Оба).
    Суффикс URL-адреса API Добавьте суффикс URL-адреса для идентификации этого API в данном экземпляре Управления API. Он должен быть уникальным в этом экземпляре Управления API.
    Базовый URL-адрес Недоступное для редактирования поле, отображающее базовый URL-адрес API
    Теги Сопоставьте API GraphQL с новыми или существующими тегами.
    Продукты Сопоставьте API GraphQL с определенным продуктом, чтобы опубликовать его.
    Шлюзы Сопоставьте API GraphQL с существующими шлюзами. Выбор шлюза по умолчанию: Managed (Управляемый).
    Версия этого API Выберите, чтобы применить схему управления версиями к API GraphQL.
  4. Нажмите кнопку создания.

  5. После создания API перейдите к схеме на вкладке Проектирование в разделе Клиентская часть.

Настройка сопоставителя

Настройте политику set-graphql-resolver для сопоставления поля в схеме с существующей конечной точкой HTTP.

Предположим, вы импортировали следующую базовую схему GraphQL и хотите настроить сопоставитель для запроса users.

type Query {
    users: [User]
}

type User {
    id: String!
    name: String!
}
  1. В меню навигации сбоку в разделе API выберите API> ваш API GraphQL.

  2. На вкладке Проектирование API GraphQL выберите Все операции.

  3. В разделе Серверная часть выберите + Добавить политику.

  4. Настройте политику set-graphql-resolver для разрешения запроса users с помощью источника данных HTTP.

    Например, следующая политика set-graphql-resolver извлекает поле users с помощью вызова GET в существующем источнике данных HTTP.

    <set-graphql-resolver parent-type="Query" field="users">
        <http-data-source>
            <http-request>
                <set-method>GET</set-method>
                <set-url>https://myapi.contoso.com/users</set-url>
            </http-request>
        </http-data-source>
    </set-graphql-resolver>
    
  5. Чтобы разрешить данные для других полей схемы, повторите предыдущий шаг.

  6. Щелкните Сохранить.

Протестируйте API GraphQL

  1. Перейдите к экземпляру Управления API.

  2. В меню навигации сбоку выберите API в разделе API.

  3. В разделе All APIs (Все API) выберите API GraphQL.

  4. Откройте вкладку Тестирование, чтобы перейти к консоли тестирования.

  5. Под разделом Headers (Заголовки):

    1. Выберите заголовок в раскрывающемся меню Name (Имя).
    2. Введите значение в поле Value (Значение).
    3. Добавьте дополнительные заголовки, нажав кнопку + Add header (Добавить заголовок).
    4. Удалите заголовки с помощью значка корзины.
  6. Если вы добавили продукт в API GraphQL, примените область продукта в разделе Apply product scope (Применить область продукта).

  7. В редакторе запросов выполните одно из следующих действий:

    1. Выберите хотя бы одно поле или подполе в списке в боковом меню. Выбранные поля и подполя отображаются в редакторе запросов.

    2. Начните вводить текст в редакторе запросов, чтобы создать запрос.

      Screenshot of adding fields to the query editor.

  8. В разделе Query variables (Переменные запроса) добавьте переменные для повторного использования одного запроса или изменения и передайте разные значения.

  9. Нажмите кнопку Отправить.

  10. Просмотрите Response (Ответ).

    Screenshot of viewing the test query response.

  11. Повторите предыдущие шаги, чтобы проверить различные полезные данные.

  12. По завершении тестирования закройте консоль тестирования.

Примечание

Подписку можно протестировать в тестовой консоли:

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

Дальнейшие действия