Политика управления версиями для служб Azure, пакетов SDK и средств CLI
Большинство служб Azure позволяют программно контролировать ресурсы и управлять ими с помощью REST API. Службы развиваются с помощью новых опубликованных версий api с различными контрактами, которые добавляют новые функции и /или изменяют их поведение.
В этой статье описывается политика, используемая командами Azure, sdk и CLI для управления версиями REST API Azure. Хотя команды Azure выполняют все усилия, чтобы придерживаться этой политики, отклонения могут иногда возникать.
Управление версиями служб
Каждая опубликованная версия API определяется значением даты в YYYY-MM-DD формате, которое называется api-version. Более новые версии имеют более поздние даты.
Все операции API требуют, чтобы клиенты указали допустимую версию API для службы с помощью api-version параметра строки запроса в URL-адресе. Например: https://management.azure.com/subscriptions?api-version=2020-01-01. Клиентские пакеты SDK и средства включают api-version значение автоматически. Дополнительные сведения см . в разделе "Пакеты SDK для клиентов" и "Версии служб" далее в этой статье.
В большинстве случаев клиенту службы потребуется взаимодействовать только с одной версией службы для доступа ко всем необходимым функциям.
Стабильные версии служб обычно остаются доступными и поддерживаются в течение многих лет, даже если новые версии становятся доступными. В большинстве случаев единственный раз, когда необходимо внедрить новую версию службы в существующем коде, следует воспользоваться преимуществами новых функций.
Стабильные версии
Большинство опубликованных версий служб являются стабильными. Стабильные версии являются обратно совместимыми, то есть любой код, который использует одну версию службы, может применять более новую стабильную версию, не требуя изменений кода для поддержания правильности или существующих функций.
Критические версии изменений
Критическое изменение версии службы не совместимо с обратной совместимостью. При принятии критической версии изменения в существующем клиентском коде может потребоваться изменение кода, чтобы гарантировать, что клиент ведет себя точно так же, как и при выборе предыдущей версии.
Критические версии изменений редки, объявлены с помощью документации и обычно предшествуют публикации предварительной версии. Публикация критической версии изменений может привести к окончательному выходу существующих стабильных версий, которые будут оставаться доступными по крайней мере через три года после критических выпусков версий изменений. Для критических изменений, опубликованных из-за проблем с безопасностью или соответствием требованиям, существующие стабильные версии служб могут оставаться доступными в течение одного года или меньше в зависимости от серьезности проблемы.
Из-за быстрых инноваций и разработок в ИИ службы, управляемые искусственным интеллектом, могут снизить минимальную доступность в течение одного года. Каждая служба будет публиковать свою политику критического изменения.
Любая служба Azure, зависящая от компонента, отличного от Майкрософт, может сократить свою политику поддержки, чтобы она соответствовала политике компонента. Любое критическое изменение из-за этого будет ссылаться на политику поставщика компонентов, показывающую дату, когда компонент больше не поддерживается.
Предварительные версии
Иногда корпорация Майкрософт публикует предварительную версию службы для сбора отзывов о предлагаемых изменениях и новых функциях. Предварительные версии служб идентифицируются с суффиксом в их суффиксе-preview, например2022-07-07-preview.api-version
Если явно не планируется внести критическое изменение предыдущей стабильной версии, новые предварительные версии включают все функции последней стабильной версии и добавить новые функции предварительной версии. Однако между версиями предварительной версии служба может нарушить любой из новых добавленных предварительных версий функций.
Предварительные версии не предназначены для долгосрочного использования. В любой момент, когда станет доступна новая стабильная или предварительная версия службы, существующие предварительные версии могут стать недоступными до 90 дней с момента доступности новой версии. Используйте предварительные версии только в ситуациях, когда вы активно разрабатываете новые функции службы, и вы готовы принять новую, не предварительную версию вскоре после выпуска. Если некоторые функции из предварительной версии выпускаются в новой стабильной версии, остальные функции по-прежнему будут опубликованы в новой предварительной версии.
Клиентские пакеты SDK и версии служб
Пакеты SDK Azure предназначены для устранения проблем с версиями служб при написании кода. Каждый пакет SDK состоит из клиентских библиотек, по одному для каждой службы, и каждая версия клиентской библиотеки предназначена для одной версии службы, на которой она используется.
При использовании пакета SDK для доступа к службе Azure использование новых версий и функций обычно требует обновления версии клиентской библиотеки, используемой приложением. Новые стабильные версии служб сопровождаются новыми выпусками клиентских библиотек. Для новых версий критических изменений новые клиентские библиотеки публикуются в виде версий выпуска точек или основных версий выпуска. Тип выпуска зависит от характера изменения службы и способа ее размещения. Только клиентские библиотеки бета-версии используют предварительные версии служб.
Клиентские библиотеки SDK поддерживают переопределение версии службы вручную. Переопределение версии службы по умолчанию клиентской библиотеки является расширенным сценарием и может привести к неожиданному поведению. Если вы используете эту функцию, протестируйте приложение тщательно, чтобы убедиться, что оно работает должным образом.
программы командной строки Azure;
Как и в случае с пакетами SDK, средства командной строки Azure (включая Azure CLI и Azure PowerShell) предназначены для разрешения использования служб управления Azure без учета версий. Для доступа к новым функциям службы часто требуется новая версия средства. Новые версии средств с обратной совместимостью выпускаются ежемесячно. Версии с критическими изменениями выпускаются примерно дважды в год или по мере необходимости для устранения критических проблем безопасности.
Средства командной строки Azure иногда могут предоставлять предварительные версии функций. Эти команды помечены Preview меткой и будут выводить предупреждение, указывающее ограниченную поддержку и потенциальные изменения в будущих версиях инструментов.