Импорт API 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 не поддерживаются.

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

  • Узнайте больше о преимуществах использования API GraphQL.
  • Добавьте API GraphQL в экземпляр Управления API.
  • Протестируйте API GraphQL.
  • Узнайте об ограничениях API GraphQL в Управлении API.

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

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

  • Существующий экземпляр Управления API. Создайте его, если у вас его нет.

  • API GraphQL.

  • Azure CLI

    • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в кратком руководстве по Azure Cloud Shell — Bash. Запуск Cloud Shell в новом окне

    • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в разделе Запуск Azure CLI в контейнере Docker.

      • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, приведены в статье Вход с помощью Azure CLI.

      • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

      • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

  • Azure PowerShell

Добавление API GraphQL

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

  2. В меню слева выберите API>+ Добавить API.

  3. В разделе Define a new API (Определение нового API) щелкните значок GraphQL.

    Снимок экрана: выбор значка GraphQL из списка API.

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

    Снимок экрана: поля для создания API GraphQL.

    Поле Description
    Отображаемое имя Это имя, под которым будет отображаться этот API GraphQL.
    имя; Необработанное имя API Graph. Оно заполняется автоматически при вводе отображаемого имени.
    Конечная точка API GraphQL Базовый URL-адрес с именем конечной точки API GraphQL.
    Например: https://example.com/your-GraphQL-name. Вы также можете использовать общедоступную конечную точку GraphQL Star Wars, такую как https://swapi-graphql.azure-api.net/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.
  5. Нажмите кнопку создания.

  6. После создания API перейдите к схеме на вкладке Проектирование в разделе Клиентская часть. Снимок экрана: изучение схемы GraphQL на портале.

Протестируйте 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. Начните вводить текст в редакторе запросов, чтобы создать запрос.

      Снимок экрана: добавление полей в редактор запросов.

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

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

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

    Снимок экрана: просмотр ответа тестового запроса.

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

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

Примечание

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

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

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