Редакции в службе управления API Azure

  • Статья

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

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

Примечание.

Портал разработчика недоступен для ценовой категории "Потребление".

С изменениями вы можете:

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

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

Доступ к конкретным редакциям

Доступ к каждой версии вашего API можно получить с помощью специально сформированного URL-адреса. Добавьте ;rev={revisionNumber} в конец URL-адреса API, но перед строкой запроса, чтобы получить доступ к определенной редакции этого API. Например, этот URL-адрес можно использовать для доступа к редакции 3 в customers API:

https://apis.contoso.com/customers;rev=3/leads?customerId=123

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

Примечание.

Необходимо ;rev={id} добавить его к идентификатору API, а не к пути URI.

Текущая редакция

Единственная редакция может быть установлена как текущая. Эта редакция будет использоваться для всех запросов API, которые не указывают явный номер редакции в URL-адресе. Вы можете вернуться к предыдущей ревизии, установив эту редакцию как текущую.

Вы можете установить текущую версию с помощью портала Azure. Если вы используете PowerShell, вы можете использовать командлет New-AzApiManagementApiRelease.

Описания редакций

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

Когда вы устанавливаете ревизию как текущую, вы также можете дополнительно указать заметку в общедоступном журнале изменений. Журнал изменений включен в портал разработчика для просмотра пользователями API. Вы можете изменить заметку в журнале изменений с помощью командлета Update-AzApiManagementApiRelease PowerShell.

Внимание

Если вы редактируете не самую последнюю версию API, вы не можете изменить следующие свойства:

  • Имя
  • Тип
  • Описание
  • Требуется подписка
  • Версия API
  • Описание версии API
  • Путь
  • Протоколы

Эти свойства можно изменить только в текущей редакции. Если изменения связаны с любыми из указанных выше свойств не самой последней версии, появится сообщение об ошибке Can't change property for non-current revision.

Переведите редакцию в автономный режим

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

Примечание.

Мы рекомендуем отключать редакции, если вы не используете их для тестирования.

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

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

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