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

Редакции в службе "Управление 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 щелкните "Создать версию из ревизии" в контекстном меню ревизии на вкладке "Ревизии".