Руководство по безопасному внесению некритических изменений в API с помощью редакций

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

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

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

Дополнительные сведения см. в статьях Версии и редакции и Управление версиями API с помощью службы управления API Azure.

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

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

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

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

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

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

2. Выберите Интерфейсы API.

3. Выберите Demo Conference API в списке API (или другой API, в который нужно внести исправления).

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

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

   

   Совет

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

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

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

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

   Примечание.

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

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

1. В списке API выберите Demo Conference API.

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

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

   Совет

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

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

5. Укажите, что создается операция POST, а затем введите имя, отображаемое имя и URL-адрес операции — test.

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. Чтобы просмотреть идентификаторы API, выполните команду az apim api list:

   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 demo-conference-api --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 echo-api --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 demo-conference-api --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 demo-conference-api --release-id 00000000000000000000000000000000 
    --service-name apim-hello-world

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

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

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

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

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

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

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

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