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

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

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

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

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

Совет

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

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

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

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

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

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

1. Войдите на портал Azure и перейдите к своему экземпляру службы Управления API.

2. В меню слева в разделе API выберите API.

3. Выберите Swagger Petstore из списка API (или другой API, к которому требуется добавить редакции).

4. Щелкните вкладку Редакции.

5. Выберите + Добавить редакцию.

   

   Совет

   Кроме того, команду Добавить редакцию можно выбрать в контекстном меню (…) API.

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

7. Нажмите кнопку создания.

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

   Примечание.

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

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

1. Выберите Swagger Petstore из списка API.

2. Выберите вкладку Конструктор в верхней части экрана.

3. Обратите внимание, что селектор исправлений (непосредственно над вкладкой "Конструктор") показывает текущую версию Revision 2.

   Совет

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

4. Щелкните + Add Operation (+ Добавить операцию).

5. Задайте для новой операции значение POST и отображаемое имя, имя и URL-адрес операции в качестве тестовой.

6. Сохраните новую операцию.

   

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

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

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

Портал

1. Выберите вкладку Исправления в меню в верхней части страницы.

2. Откройте контекстное меню (…) для редакции Revision 2.

3. Выберите Сделать текущей.

4. Установите флажок Post to Public Change log for this API (Записать в общедоступный журнал изменений для этого API), если нужно опубликовать примечания об этом изменении. Введите описание внесенного изменения, которое будет отображаться для разработчиков, например: Тестирование исправлений. Добавлена новая операция test.

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

   

Azure CLI

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

• Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  

• Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

  • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

  • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

  • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

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

1. Выполните команду 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.

2. Чтобы создать выпуск с заметкой о выпуске, выполните команду 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.'
   

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

3. Чтобы просмотреть выпуски, выполните команду 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
   

   Заметки, которые вы укажете, отобразятся в журнале изменений. Вы увидите их в выходных данных предыдущей команды.

4. При создании выпуска параметр --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 и журнал изменений.

1. Перейдите к экземпляру Управления API на портале Azure.
2. В меню слева в разделе API выберите API.
3. Выберите Портал разработчика в верхнем меню.
4. На портале разработчика выберите API и выберите Swagger Petstore.
5. Обратите внимание на то, что теперь доступна новая операция test.
6. Щелкните Журнал изменений рядом с именем API.
7. Обратите внимание на запись журнала изменений в этом списке.

Доступ к редакции 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