Руководство. Использование исправлений для безопасного внесения изменений в API без нарушения

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

Когда API используется разработчиками, в конечном итоге необходимо внести изменения в этот API, не нарушая вызовы API. Полезно также сообщать разработчикам о внесенных изменениях.

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

Дополнительные сведения см. в разделе "Версии и редакции".

Совет

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

В этом руководстве описано следующее:

Добавление новой редакции
Внесение неразрывных изменений в редакцию
Назначение редакции текущей и добавление записи журнала изменений
Обзор портала разработчика для просмотра изменений и журнала изменений
Доступ к редакции API

Необходимые компоненты

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

Добавление новой редакции

Войдите на портал Azure и перейдите к своему экземпляру службы Управления API.
В меню слева в разделе API выберите API.
Выберите Swagger Petstore из списка API или другое API, к которому вы хотите добавить изменения.
Щелкните вкладку Редакции.
Выберите + Добавить редакцию.

Совет

Кроме того, команду Добавить редакцию можно выбрать в контекстном меню (…) API.
Укажите описание новой версии, чтобы легче помнить, для чего она предназначена.
Нажмите кнопку создания.

Новая редакция создана.

Примечание.

Исходный API остается в редакции Revision 1. Это редакция, которую пользователи продолжают вызывать, пока не решите сделать другую редакцию текущей.

Внесение неразрывных изменений в редакцию

Выберите Swagger Petstore из списка API.
Выберите Дизайн в верхней части экрана.

Селектор редакции над вкладкой конструктора отображает версию 2, как выбрано в данный момент.

Совет

Используйте селектор редакции для переключения между редакциям, с которыми вы хотите работать.
Щелкните + Add Operation (+ Добавить операцию).
Задайте для новой операции значение POST и отображаемое имя, имя и URL-адрес операции в качестве тестовой.
Сохраните новую операцию.

Теперь вы внесли изменение в редакцию Revision 2.
Используйте селектор редакции в верхней части страницы, чтобы вернуться к редакции Revision 1.

Обратите внимание, что новая операция не отображается в редакции Revision 1.

Назначение редакции текущей и добавление записи журнала изменений

Портал
Azure CLI

В меню в верхней части страницы выберите Версии.
Откройте контекстное меню (…) для редакции Revision 2.
Выберите Сделать текущей.
Если вы хотите опубликовать заметки об этом изменении, выберите "Опубликовать в общедоступный журнал изменений" для этого API. Введите описание внесенного изменения, которое будет отображаться для разработчиков, например: Тестирование исправлений. Добавлена новая операция test.

Теперь редакция Revision 2 является текущей.

Чтобы начать работу с Azure CLI:

Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см. в статье "Начало работы с Azure Cloud Shell".
Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.
- Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других параметрах входа см. в статье "Проверка подлинности в Azure с помощью Azure CLI".
- Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений и управление ими с помощью Azure CLI.
- Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Используйте указанную ниже процедуру для создания и обновления выпуска.

Выполните команду az api list, чтобы просмотреть идентификаторы API:
```
az apim api list --resource-group apim-hello-word-resource-group \
    --service-name apim-hello-world --output table
```
Идентификатор API, используемый в следующей команде, имеет значение Name. Версия API находится в столбце ApiRevision.

Чтобы создать выпуск с заметкой о выпуске, выполните команду az apim api release create:

az apim api release create --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --api-revision 2 --service-name apim-hello-world \
    --notes 'Testing revisions. Added new "test" operation.'

Выпущенная версия станет текущей версией.

Чтобы просмотреть выпуски, выполните команду az apim api release list:
```
az apim api release list --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --service-name apim-hello-world --output table
```
Заметки, которые вы укажете, отобразятся в журнале изменений. Вы увидите их в выходных данных предыдущей команды.
При создании выпуска параметр --notes является необязательным. Вы можете добавить или изменить заметки позже с помощью команды az apim api release update:
```
az apim api release update --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 \
    --service-name apim-hello-world --notes "Revised notes."
```
Используйте значение в столбце Name для идентификатора выпуска.

Вы можете удалить любой выпуск с помощью команды az apim api release delete:

az apim api release delete --resource-group apim-hello-word-resource-group \
    --api-id swagger-petstore --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

Обзор портала разработчика для просмотра изменений и журнала изменений

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

Перейдите к экземпляру Управления API на портале Azure.
В меню слева в разделе API выберите API.
Выберите Портал разработчика в верхнем меню.
На портале разработчика выберите API и выберите Swagger Petstore.
Обратите внимание на то, что теперь доступна новая операция test.
Выберите "Изменить журнал" рядом с именем API.
Обратите внимание на запись журнала изменений в этом списке.

Доступ к редакции API

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

https://apim-hello-world.azure-api.net/store/pet/1;rev=2/

Url-адреса для исправлений API можно найти на вкладке "Редакции" в портал Azure.

Совет

Вы можете получить доступ к текущей редакции API, используя путь API без ;rev строки, помимо полного URL-адреса, добавляемого ;rev={revisionNumber} к пути API.

Итоги

Из этого руководства вы узнали, как:

Добавление новой редакции
Внесение неразрывных изменений в редакцию
Назначение редакции текущей и добавление записи журнала изменений
Обзор портала разработчика для просмотра изменений и журнала изменений
Доступ к редакции API

Следующий шаг

Перейдите к следующему руководству:

Публикация нескольких версий API

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-01-30