如何使用 Git 保存和配置 API 管理服务
可用性
重要
此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用 。
每个 API 管理服务实例都保留一个配置数据库,该数据库包含关于服务实例的配置和元数据的信息。 可以通过在 Azure 门户中更改设置、使用 Azure PowerShell 或 Azure CLI 等 Azure 工具或进行 REST API 调用对服务实例进行更改。 除了这些方法,还可以使用 Git 管理服务实例配置,从而为以下场景tight支持:
- 配置版本控制 - 下载并存储不同版本的服务配置
- 批量配置更改 - 在本地存储库中对服务配置的多个部分进行更改,然后通过单个操作将更改集成回服务器
- 熟悉的 Git 工具链和工作流 - 使用熟悉的 Git 工具链和工作流
下图显示配置 API 管理服务实例的不同方式的概述。
使用 Azure 门户、Azure PowerShell、Azure CLI 或 REST API 等 Azure 工具对服务进行更改时,实际上是在使用 https://{name}.management.azure-api.cn
终结点管理服务配置数据库,如图表的右侧所示。 图左侧说明了如何针对位于 https://{name}.scm.azure-api.cn
的服务使用 Git 和 Git 存储库管理服务配置。
以下步骤提供了使用 Git 管理 API 管理服务实例的概述。
- 访问服务中的 Git 配置
- 将服务配置数据库保存到 Git 存储库
- 将 Git 存储库克隆到本地计算机
- 将最新的存储库提取到本地计算,并将更改提交并推送回存储库
- 将更改从存储库部署到服务配置数据库中
本文介绍如何启用和使用 Git 管理服务配置,并提供 Git 存储库中的文件和文件夹的参考。
重要
此功能设计用于中小型 API 管理服务配置,例如导出大小小于 10 MB 或少于 10,000 个实体的情况。 处理 Git 命令时,实体(产品、API、操作、架构等)数量较多的服务可能会发生异常故障。 如果遇到此类故障,请减小服务配置的大小,然后重试。 如需帮助,请联系 Azure 支持团队。
访问服务中的 Git 配置
在 Azure 门户中导航到自己的 API 管理实例。
在左侧菜单中的“部署和基础结构”下方,选择“存储库”。
将服务配置保存到 Git 存储库
注意
任何未定义为命名值的机密将存储在存储库中,并且仍将保留在其历史记录中。 命名值提供了安全的位置来管理跨 API 配置和策略的常量字符串值(包括机密),因此无需将它们直接存储在策略语句中。 有关详细信息,请参阅在 Azure API 管理策略中使用命名值。
克隆存储库前,请将服务配置的当前状态保存到存储库中。
在“存储库”页面上,选择“保存到存储库”。
在确认屏幕上进行任何所需的更改,例如用于保存配置的分支的名称,然后选择“保存”。
片刻后配置已保存,并显示存储库的配置状态,包括上次配置更改和服务配置与存储库之间上次同步的日期和时间。
将配置保存到存储库后,可以克隆它。
有关使用 REST API 保存服务配置的信息,请参阅租户配置 - 保存。
获取访问凭据
若要克隆存储库以及指向存储库的 URL,需要用户名和密码。
在“存储库”页面上,选择页面顶部附近的“访问凭据”。
记下“访问凭据”页面上提供的用户名。
若要生成密码,首先需要确保“失效”设置为所需的失效日期和时间,然后选择“生成”。
重要
记下此密码。 离开此页面后,不会再次显示该密码。
将存储库克隆到本地计算机
下面的示例使用 Git for Windows 中提供的 Git Bash 工具,但你也可以使用自己熟悉的任何 Git 工具。
在所需的文件夹中打开 Git 工具,然后运行以下命令,将 Git 存储库克隆到本地计算机:
git clone https://{name}.scm.azure-api.cn/
收到提示时,请提供用户名和密码。
如果收到任何错误,请尝试将 git clone
命令修改为包含用户名和密码,如以下示例所示。
git clone https://username:password@{name}.scm.azure-api.cn/
如果这提供了一个错误,请尝试对命令的密码部分进行 URL 编码。 执行此操作的一个快速方法是打开 Visual Studio,并在“即时窗口”中发出以下命令。 要打开“即使窗口”,请在 Visual Studio 中打开任意解决方案或项目(或创建新的空白控制台应用程序),并从“调试”菜单中依次选择“Windows”、“即时”。
?System.Net.WebUtility.UrlEncode("password from the Azure portal")
将编码密码与用户名和存储库位置一起用于构造 Git 命令。
git clone https://username:url encoded password@{name}.scm.azure-api.cn/
克隆完成后,运行如下所示的命令将目录更改为自己的存储库。
cd {name}.scm.azure-api.cn/
如果将配置保存到默认分支 (master
) 以外的其他分支,请检查该分支:
git checkout <branch_name>
克隆存储库后,可在本地文件系统中查看和处理它。 有关详细信息,请参阅本地 Git 存储库的文件和文件夹结构参考。
使用最新的服务实例配置更新本地存储库
如果在 Auzre 门户中或使用其他 Azure 工具对 API 管理服务实例进行了更改,在使用最新的更改更新本地存储库之前,必须将这些更改保存到本地存储库。
若要使用 Azure 门户保存更改,请在 API 管理实例的“存储库”选项卡上,选择“保存到存储库”。
然后,更新本地存储库:
确保位于本地存储库的文件夹中。 如果刚完成
git clone
命令,则必须通过运行以下命令将目录更改为存储库。cd {name}.scm.azure-api.cn/
在本地存储库的文件夹中,发出以下命令。
git pull
将更改从本地存储库推送到服务器存储库
要将更改从本地存储库推送到服务器存储库,必须提交更改,然后将它们推送到服务器存储库。 要提交更改,请打开 Git 命令工具、切换到本地存储库的目录,并发出以下命令。
git add --all
git commit -m "Description of your changes"
要将所有提交推送到服务器,请运行以下命令。
git push
将服务配置更改部署到 API 管理服务实例
将本地更改提交并推送到服务器存储库后,可将它们部署到 API 管理服务实例。
在 Azure 门户中导航到自己的 API 管理实例。
在左侧菜单中的“部署和基础结构”下,选择“存储库”>“部署到 API 管理”。
在“部署存储库配置”页面,输入包含所需配置更改的分支的名称,并有选择性地选择“移除已删除产品的订阅”。 选择“保存” 。
有关使用 REST API 执行此操作的信息,请参阅租户配置 - 部署。
本地 Git 存储库的文件和文件夹结构参考
本地 Git 存储库中的文件和文件夹包含有关服务实例的配置信息。
Item | 说明 |
---|---|
根 api-management 文件夹 | 包含服务实例的顶级配置 |
apiReleases 文件夹 | 包含服务实例中 API 版本的配置 |
apis 文件夹 | 包含服务实例中 API 的配置 |
apiVersionSets 文件夹 | 包含服务实例中 API 版本集的配置 |
backends 文件夹 | 包含服务实例中后端资源的配置 |
groups 文件夹 | 包含服务实例中的组的配置 |
policies 文件夹 | 包含服务实例中的策略 |
portalStyles 文件夹 | 包含服务实例中的开发人员门户自定义的配置 |
portalTemplates 文件夹 | 包含服务实例中开发人员门户模板的配置 |
products 文件夹 | 包含服务实例中产品的配置 |
templates 文件夹 | 包含服务实例中电子邮件模板的配置 |
每个文件夹都可包含一个或多个文件,并且在某些情况下可包含一个或多个文件夹,例如,每个 API、产品或组对应一个文件夹。 每个文件夹内的文件都特定于文件夹名称所述的实体类型。
文件类型 | 目的 |
---|---|
json | 关于相应实体的配置信息 |
html | 关于实体的说明,通常显示在开发人员门户中 |
xml | 策略语句 |
css | 用于开发人员门户自定义的样式表 |
可在本地文件系统中创建、删除、编辑和管理这些文件,并将更改部署回 API 管理服务实例。
根 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 的描述,对应于 REST API 中 API 实体的description
属性。apis\<api name>\operations\
- 包含<operation name>.description.html
文件的文件夹,这些文件映射到 API 的操作中。 每个文件包含 API 中单个操作的说明,该说明映射到 REST API 中操作实体的description
属性。
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
- 产品的描述,对应于 REST API 中产品实例的description
属性。
模板
templates
文件夹包含服务实例的电子邮件模板配置。
<template name>\configuration.json
- 电子邮件模板的配置。<template name>\body.html
- 电子邮件模板的正文。
后续步骤
有关管理服务实例的其他方法的信息,请参阅: