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

Версии в службе управления API Azure

  • Статья

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

Версии позволяют создавать группы связанных API для разработчиков. Версии можно использовать для безопасной обработки критических изменений в API. Клиенты могут использовать новую версию API, когда будут готовы, в то время как существующие клиенты продолжают использовать более раннюю версию. Версии различаются по идентификатору версии (который представляет собой любое строковое значение), а схема управления версиями позволяет клиентам определить, какую версию API они хотят использовать.

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

С помощью версий можно:

  • Одновременно публиковать несколько версий API.
  • Использовать путь, строку запроса или заголовок, чтобы различать версии.
  • Использовать любое строковое значение, которым вы хотите идентифицировать версию, это значение может быть числом, датой или именем.
  • Отображать версии API, сгруппированные на портале разработчика.
  • Использовать существующие (неверсионные) API и создавать их новые версию, не нарушая работу существующих клиентов.

Начните работать с версиями, следуя нашему пошаговому руководству.

Схемы управления версиями

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

Управление версиями с привязкой к пути

При использовании схемы управления версиями с привязкой к пути идентификатор версии должен быть включен в URL-адрес для любых запросов API.

Например, https://apis.contoso.com/products/v1 и https://apis.contoso.com/products/v2 могут ссылаться на один и тот же products API, но на версии v1 и v2 соответственно.

Формат URL-адреса запроса API при использовании управления версиями с привязкой к пути: https://{yourDomain}/{apiName}/{versionIdentifier}/{operationId}.

Управление версиями с привязкой к заголовку

При использовании схемы управления версиями с привязкой к заголовку идентификатор версии должен быть включен в заголовок HTTP-запроса для любых запросов API. Можно указать имя заголовка HTTP-запроса.

Например, можно создать пользовательский заголовок с именем Api-Version, а клиенты могут указать v1 или v2 в значении этого заголовка.

Управление версиями с привязкой к строкам запроса

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

Формат URL-адреса запроса API при использовании управления версиями с привязкой к пути: https://{yourDomain}/{apiName}/{operationId}?{queryStringParameterName}={versionIdentifier}.

Например, https://apis.contoso.com/products?api-version=v1 и https://apis.contoso.com/products?api-version=v2 могут ссылаться на один и тот же products API, но на версии v1 и v2 соответственно.

Примечание.

Параметры запроса не допускаются в свойстве servers спецификации OpenAPI. Если вы экспортируете спецификацию OpenAPI из версии API, строка запроса не будет отображаться в URL-адресе сервера.

Исходные версии

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

Как представлены версии

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

Каждая версия API поддерживается как собственный ресурс API, который затем связывается с набором версий. Набор версий может содержать API с разными операциями или политиками. Вы можете внести значительные изменения между версиями в наборе.

Портал Azure создает наборы версий. Имя и описание набора версий можно изменить на портале Azure.

Набор версий автоматически удаляется при удалении окончательной версии.

Вы можете просматривать наборы версий и управлять ими напрямую с помощью Azure CLI, Azure PowerShell, шаблонов Resource Manager или API Resource Manager Azure.

Примечание.

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

Перенос неверсионных API в API с версиями

При использовании портала Azure для включения управления версиями в существующем API следующие изменения вносятся в ресурсы Управления API:

  • Создается новый набор версий.
  • Существующая версия поддерживается и настраивается в качестве Original версии API. API связан с набором версий, но не требует указания идентификатора версии.
  • Новая версия создается как новый API и связывается набором версий. Доступ к этому новому API необходимо получить с помощью схемы управления версиями и идентификатора.

Версии и редакции

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

Если вы обнаружите, что ваша редакция содержит критические изменения, или если вы хотите официально превратить вашу редакцию в бета-версию или тестовую версию, вы можете создать версию на основе редакции. Используя портал Azure, щелкните "Создать версию из редакции" в контекстном меню редакции на вкладке "Редакции".

Портал разработчика

Портал разработчика перечисляет каждую версию API отдельно.

Управление API портал разработчика, отображающий список версий API

Сведения об API также отображают список всех версий этого API. Версия Original отображается без идентификатора версии.

Управление API портал разработчика, отображающий сведения о API и список версий для этого API

Совет

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