Руководство по Публикация нескольких версий API

  • Статья

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

Иногда нецелесообразно предоставлять всем вызывающим сторонам одну версию API. Если вызывающим сторонам требуется выполнить обновление до более поздней версии, они хотят, чтобы сделать это было просто. Как показано в этом учебнике, в Управлении API Azure можно использовать несколько версий.

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

В этом руководстве описано следующее:

  • добавление новой версии в существующий интерфейс API;
  • выбор схемы версии;
  • Добавление версии в продукт
  • Обзор портала разработчика для просмотра версии

Версия, показанная на портале Azure

Необходимые компоненты

Добавление новой версии

  1. Перейдите к экземпляру Управления API на портале Azure.
  2. Выберите Интерфейсы API.
  3. В списке API выберите Demo Conference API.
  4. Выберите контекстное меню (...) рядом с элементом Demo Conference API.
  5. Выберите Добавить версию.

Контекстное меню API — добавление версии

Совет

Версии также могут быть включены при создании API. На экране Добавление API выберите элемент Управлять версией этого API?.

Выбор схемы управления версиями

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

Введите значения из следующей таблицы. Затем выберите Создать, чтобы создать версию.

Экран добавления версии

Параметр значение Описание
Имя demo-conference-api-v1 Уникальное имя в экземпляре Управления API.

Так как версия фактически является новым API, созданным в результате исправления API, этот параметр является новым именем API.
Схема управления версиями Путь Способ, с помощью которого вызывающие стороны указывают версию API.
Идентификатор версии версия 1 Относящийся к схеме индикатор версии. Это суффикс URL-адреса API для элемента Путь.

Если выбран параметр Заголовок или Строка запроса, введите дополнительное значение: имя заголовка или параметр строки запроса.

Отобразится пример использования.
Товары Unlimited Необязательно. Один или несколько продуктов, с которыми связана версия API. Чтобы опубликовать API, его нужно связать с определенным продуктом. Кроме того, можно добавить версию в продукт позже.

После создания версия отображается под элементом Demo Conference API в списке API. Теперь вы увидите два API: Original и v1.

Версии, перечисленные в списке API на портале Azure

Примечание.

Если добавить версию для API без управления версиями, будет автоматически создаваться версия Original в соответствии с URL-адресом по умолчанию. Создание версии Original гарантирует, что работа вызывающих сторон не будет нарушена в процессе добавления версии. Если вы сразу создадите API с управлением версиями, то версия Original не будет создаваться.

Изменение версии

После добавления версии ее можно изменить и настроить как API, который отделен от исходного. Изменение одной версии не влияет на другую. Например, добавьте или удалите операции API или измените спецификацию OpenAPI. Дополнительные сведения см. в статье Изменение API.

Добавление версии в продукт

Чтобы для вызывающих сторон отображалась новая версия, ее необходимо добавить в продукт. Если вы еще не добавили версию в продукт, вы можете сделать это в любое время.

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

  1. Перейдите к экземпляру Управления API на портале Azure.
  2. Выберите Продукты>Без ограничений>API>+ Добавить.
  3. Выберите Demo Conference API, версия v1.
  4. Щелкните Выбрать.

Добавление версии в продукт

Использование наборов версий

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

Вы можете напрямую взаимодействовать с набором версий с помощью Azure CLI:

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure 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.

Чтобы просмотреть все наборы версий, выполните команду az apim api versionset list:

az apim api versionset list --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --output table

Когда портал Azure создает набор версий, ему присваивается буквенно-цифровое имя, которое отображается в столбце Имя списка. Это имя можно использовать в других командах Azure CLI.

Чтобы просмотреть сведения о наборе версий, выполните команду az apim api versionset show:

az apim api versionset show --resource-group apim-hello-world-resource-group \
    --service-name apim-hello-world --version-set-id 00000000000000000000000

Дополнительные сведения о наборах версий см. в разделе Версии в Управлении API Azure.

Обзор портала разработчика для просмотра версии

Если вы использовали портал разработчика, вы можете просмотреть версии API.

  1. Выберите Портал разработчика в верхнем меню.
  2. Выберите API, а затем — Demo Conference API.
  3. Появится раскрывающийся список с несколькими версиями рядом с именем API.
  4. Выберите v1.
  5. Обратите внимание на URL-адрес запроса первой операции в списке. В нем видно, что путь URL-адреса API содержит v1.

Следующие шаги

Из этого руководства вы узнали, как:

  • добавление новой версии в существующий интерфейс API;
  • выбор схемы версии;
  • Добавление версии в продукт
  • Обзор портала разработчика для просмотра версии

Перейдите к следующему руководству:

Настройка стиля страниц для портала разработчика