Сохранение и настройка конфигурации службы управления API с помощью Git

Статья
05/12/2023

ОБЛАСТЬ ПРИМЕНЕНИЯ: Разработчик | Базовый | Стандартный | Премиум

Каждый экземпляр службы управления API поддерживает базу данных конфигурации, содержащую сведения о конфигурации и метаданных для экземпляра службы. Внесение изменений в экземпляр службы выполняется путем изменения параметра на портале Azure или с помощью инструмента Azure, например Azure PowerShell или Azure CLI. Помимо этих методов для управления конфигурацией экземпляра службы можно использовать Git для реализации следующих сценариев:

Управление версиями конфигурации — скачивание и хранение различных версий конфигурации службы.
Массовые изменения конфигурации — внесение изменений в несколько частей конфигурации службы в локальном репозитории и интеграция изменений на сервер с помощью одной операции.
Знакомая цепочка инструментов и рабочий процесс Git — использование знакомых средств и рабочих процессов Git.

На схеме ниже приведен обзор различных способов настройки экземпляра службы управления API.

Схема со сравнением способов настройки Управления API Azure.

При внесении изменений в службу с использованием портала Azure, инструмента Azure, например Azure PowerShell или Azure CLI, или REST API управление базой данных конфигурации службы осуществляется с помощью конечной точки https://{name}.management.azure-api.net, как показано в правой части схемы. В левой части схемы демонстрируется вариант управления конфигурацией службы с помощью Git и репозитория Git для вашей службы, расположенного в https://{name}.scm.azure-api.net.

Ниже приведены действия с общими сведениями по управлению экземпляром службы управления API с помощью Git.

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

В этой статье описывается включение и использование Git для управления конфигурацией и содержатся справочные сведения о файлах и папках в репозитории Git.

Внимание

Эта функция предназначена для работы с малой и средней конфигурациями службы "Управление API", например с экспортируемым размером менее 10 МБ или с менее чем 10 000 сущностей. Службы с большим количеством объектов (продуктов, API, операций, схем и т.п.) могут столкнуться с непредвиденными сбоями при обработке команд Git. При возникновении таких сбоев уменьшите размер конфигурации службы и повторите попытку. Если вам нужна помощь, обратитесь в службу поддержки Azure.

Доступ к конфигурации Git в службе

Перейдите к своему экземпляру управления API на портале Azure.
В меню слева в разделе Развертывание и инфраструктура выберите Репозиторий.

Снимок экрана: доступ к конфигурации Git для Управления API.

Сохранение конфигурации службы в репозитории Git

Внимание

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

Перед клонированием репозитория сохраните текущее состояние конфигурации службы в репозитории.

На странице Репозиторий выберите Сохранить в репозиторий.
Внесите необходимые изменения на экране подтверждения, например имя ветви для сохранения конфигурации, и нажмите кнопку Сохранить.

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

Сохраненную в репозитории конфигурацию можно клонировать.

Сведения о сохранении конфигурации службы с помощью REST API см. в разделе Конфигурация клиента — Сохранение.

Получение учетных данных для доступа

Чтобы клонировать репозиторий, помимо URL-адреса репозитория вам потребуется имя пользователя и пароль.

На странице Репозиторий выберите Учетные данные для доступа в верхней части страницы.
Обратите внимание на имя пользователя, предоставленное на странице Учетные данные для доступа.
Чтобы создать пароль, проверьте, указаны ли в строке Срок действия нужные значения даты и времени срока действия, а затем нажмите кнопку Создать.

Внимание

Запомните этот пароль. После закрытия этой страницы пароль больше не будет отображаться.

клонировать репозиторий на локальный компьютер;

В следующих примерах применяется средство Git Bash из Git для Windows, но можно использовать любое знакомое вам средство Git.

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

git clone https://{name}.scm.azure-api.net/

При появлении запроса введите имя пользователя и пароль.

При появлении ошибок попробуйте изменить команду git clone так, чтобы она включала в себя имя пользователя и пароль, как показано в следующем примере.

git clone https://username:password@{name}.scm.azure-api.net/

Если ошибка возникнет и в этом случае, попробуйте использовать кодирование URL части пароля, содержащегося в команде. Чтобы быстро решить эту задачу, откройте Visual Studio и выполните следующую команду в окне интерпретации. Чтобы открыть окно интерпретации, откройте любое решение или проект в Visual Studio (или создайте пустое консольное приложение), а затем выберите Окна и Интерпретация в меню Отладка.

?System.Net.WebUtility.UrlEncode("password from the Azure portal")

Зашифрованный пароль вместе с именем пользователя и расположением репозитория можно использовать для создания команды git.

git clone https://username:url encoded password@{name}.scm.azure-api.net/

После завершения клонирования измените каталог на репозиторий, выполнив команду, аналогичную приведенной ниже.

cd {name}.scm.azure-api.net/

Если вы сохранили конфигурацию в ветвь, отличную от ветви по умолчанию (master), ознакомьтесь со следующей ветвью:

git checkout <branch_name>

После клонирования репозиторий доступен для просмотра и работы в локальной файловой системе. Дополнительные сведения см. в разделе Справочные сведения по структуре файлов и папок локального репозитория Git.

Обновление локального репозитория самой последней конфигурацией экземпляра службы

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

Чтобы сохранить изменения с помощью портала Azure, выберите Сохранить в репозиторий на вкладке Репозиторий для экземпляра Управления API.

Чтобы обновить локальный репозиторий:

Убедитесь, что выбрана папка локального хранилища. Если вы только что завершили команду git clone, необходимо изменить каталог на репозиторий, выполнив команду, аналогичную приведенной ниже.
```
cd {name}.scm.azure-api.net/
```
В папке для локального репозитория выполните приведенную ниже команду.
```
git pull
```

Отправка изменений из локального репозитория в репозиторий сервера

Чтобы отправить изменения из локального репозитория в репозиторий сервера, необходимо зафиксировать изменения и после этого отправить их в репозиторий сервера. Чтобы зафиксировать изменения, откройте командное средство Git, перейдите в каталог локального репозитория и выполните следующие команды.

git add --all
git commit -m "Description of your changes"

Для отправки всех фиксаций на сервер выполните следующую команду.

git push

Развертывание изменений конфигурации службы в экземпляре Управления API

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

Перейдите к своему экземпляру управления API на портале Azure.
В меню слева в разделе Развертывание и инфраструктура выберите Репозиторий>Развертывание в Управлении API.
На странице Развертывание конфигурации репозитория введите имя ветви, содержащей необходимые изменения конфигурации, и при необходимости выберите Удалить подписки удаленных продуктов. Выберите Сохранить.

Сведения о выполнении этой операции с помощью REST API см. в статье Конфигурация клиента — развертывание.

Справочные сведения по структуре файлов и папок локального репозитория Git

В файлах и папках в локальном репозитории Git содержатся сведения о конфигурации экземпляра службы.

Позиция	Description
Корневая папка api-management	Содержит конфигурацию верхнего уровня для экземпляра службы
Папка apiReleases	Содержит конфигурацию для выпусков API в экземпляре службы
Папка apis	Содержит конфигурацию для API в экземпляре службы
Папка apiVersionSets	Содержит конфигурацию для версии API в экземпляре службы
Папка серверных компонентов	Содержит конфигурацию для ресурсов серверной части в экземпляре службы
Папка groups	Содержит конфигурацию для групп в экземпляре службы
Папка policies	Содержит политики в экземпляре службы
Папка portalStyles	Содержит конфигурацию для настроек портала разработчика в экземпляре службы
Папка portalTemplates	Содержит конфигурацию для шаблонов портала разработчика в экземпляре службы
Папка products	Содержит конфигурацию для продуктов в экземпляре службы
Папка templates	Содержит конфигурацию для шаблонов электронной почты в экземпляре службы

В каждой папке может находиться один или несколько файлов и в некоторых случаях одна или несколько папок, например папка для каждого API, продукта или группы. Файлы в каждой папке специфичны для типа сущности, описанного в имени папки.

Тип файла	Характер использования
json	Сведения о конфигурации соответствующей сущности
html	Описания сущности, часто отображаемые на портале разработчика
xml	Правила политики
css	Таблицы стилей для настройки портала разработчика

Эти файлы можно создавать, удалять, изменять и контролировать в локальной файловой системе. А изменения можно снова развернуть в экземпляре службы управления API.

Примечание.

Указанные далее сущности отсутствуют в репозитории Git и не могут быть настроены с помощью Git.

Пользователи
Подписки
Именованные значения
Сущности портала разработчика, отличные от стилей и шаблонов
Фрагменты политики

Корневая папка api-management

Корневая папка api-management содержит файл configuration.json со сведениями верхнего уровня об экземпляре службы в следующем формате.

{
  "settings": {
    "RegistrationEnabled": "True",
    "UserRegistrationTerms": null,
    "UserRegistrationTermsEnabled": "False",
    "UserRegistrationTermsConsentRequired": "False",
    "DelegationEnabled": "False",
    "DelegationUrl": "",
    "DelegatedSubscriptionEnabled": "False",
    "DelegationValidationKey": "",
    "RequireUserSigninEnabled": "false"
  },
  "$ref-policy": "api-management/policies/global.xml"
}

Первые четыре параметра (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled и UserRegistrationTermsConsentRequired) соответствуют указанным далее настройкам на вкладке Удостоверения в секции Портал разработчика.

Параметр удостоверения	Соответствует параметру
RegistrationEnabled	Присутствие поставщика удостоверений с именем пользователя и паролем.
UserRegistrationTerms	Условия использования при регистрации пользователя
UserRegistrationTermsEnabled	Показывать условия использования на странице регистрации
UserRegistrationTermsConsentRequired	Требовать согласия
RequireUserSigninEnabled	Перенаправлять анонимных пользователей на страницу входа

Следующие четыре параметра (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled и DelegationValidationKey) соответствуют указанным далее настройкам на вкладке Делегирование в разделе Портал разработчика.

Параметр делегирования	Соответствует параметру
DelegationEnabled	Флажок Делегировать вход и регистрацию
DelegationUrl	URL-адрес конечной точки делегирования
DelegatedSubscriptionEnabled	Делегировать подписку на продукт
DelegationValidationKey	Делегировать ключ проверки

Последний параметр $ref-policyсоответствует глобальному файлу правил политики для экземпляра службы.

Папка apiReleases

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

apiReleases\<api release Id>\configuration.json — конфигурация выпуска, содержащая сведения о датах выпуска. Это те же сведения, которые возвращаются при вызове операции Получить определенный выпуск.

Папка apis

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

apis\<api name>\configuration.json — это конфигурация для API, которая содержит сведения о серверном URL-адресе службы и операциях. Это те же сведения, которые возвращаются при вызове операции Получить определенный API.
apis\<api name>\api.description.html — описание API, соответствующее свойству description сущности API в REST API.
apis\<api name>\operations\ — эта папка содержит файлы <operation name>.description.html, соответствующие операциям в API. Каждый файл содержит описание одной операции в API, которая сопоставляется со свойством descriptionсущности operation в REST API.

Папка apiVersionSets

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

apiVersionSets\<api version set Id>\configuration.json — конфигурация для набора версий. Это те же сведения, которые возвращаются при вызове операции Получить определенный набор версий.

Папка groups

Папка groups содержит папку для каждой группы, определенной в экземпляре службы.

groups\<group name>\configuration.json — конфигурация для группы. Это те же сведения, которые возвращаются при вызове операции Получить определенную группу .
groups\<group name>\description.html — это описание группы, которое соответствует свойству description сущности группы.

Папка policies

Папка policies содержит правила политики для экземпляра службы.

policies\global.xml содержит политики, определенные в глобальной области для экземпляра службы.
policies\apis\<api name>\ — если в области API определены какие-либо политики, они содержатся в этой папке.
Папка policies\apis\<api name>\<operation name>\ — если в области операции определены какие-либо политики, они содержатся в этой папке в файлах <operation name>.xml, соответствующих правилам политики для каждой операции.
policies\products\ — если в области продукта определены какие-либо политики, они содержатся в этой папке в файлах <product name>.xml, соответствующих правилам политики для каждого продукта.

Папка portalStyles

Папка portalStyles содержит конфигурацию и таблицы стилей для настройки устаревшего портала разработчика для экземпляра службы.

portalStyles\configuration.json содержит имена таблиц стилей, используемых на портале разработчика.
portalStyles\<style name>.css — каждый файл <style name>.css содержит стили для портала разработчика (Preview.css и Production.css по умолчанию).

Папка portalTemplates

Папка portalTemplates содержит шаблоны для настройки устаревшего портала разработчика экземпляра службы.

portalTemplates\<template name>\configuration.json — конфигурация шаблона.
portalTemplates\<template name>\<page name>.html — исходные и измененные HTML-страницы шаблона.

Папка products

Папка products содержит папку для каждого продукта, определенного в экземпляре службы.

products\<product name>\configuration.json — это конфигурация для продукта. Это те же сведения, которые возвращаются при вызове операции Получить определенный продукт .
products\<product name>\product.description.html — это описание продукта, которое соответствует свойству descriptionсущности product в REST API.

шаблоны

Папка templates содержит конфигурацию для шаблонов электронной почты экземпляра службы.

<template name>\configuration.json — это конфигурация для шаблона электронной почты.
<template name>\body.html — это текст сообщения электронной почты.

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

Сведения о других способах управления экземпляром службы см. в приведенных ниже статьях.

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

Сохранение и настройка конфигурации службы управления API с помощью Git

Доступ к конфигурации Git в службе

Сохранение конфигурации службы в репозитории Git

Получение учетных данных для доступа

клонировать репозиторий на локальный компьютер;

Обновление локального репозитория самой последней конфигурацией экземпляра службы

Отправка изменений из локального репозитория в репозиторий сервера

Развертывание изменений конфигурации службы в экземпляре Управления API

Справочные сведения по структуре файлов и папок локального репозитория Git

Корневая папка api-management

Папка apiReleases

Папка apis

Папка apiVersionSets

Папка groups

Папка policies

Папка portalStyles

Папка portalTemplates

Папка products

шаблоны

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

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

Дополнительные ресурсы