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

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

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

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

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

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

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

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

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

Версионирование на основе путей

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

Например, и https://apis.contoso.com/products/v2 может ссылаться на тот же products API, https://apis.contoso.com/products/v1 но на версии 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=v2 может ссылаться на тот же products API, https://apis.contoso.com/products?api-version=v1 но на версии v1 и v2 соответственно.

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

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

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

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

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

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

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

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

Перенос неверсионированного API в версионированное API

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

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

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

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

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

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

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

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