如何使用 Git 保存和配置 API 管理服务

项目
07/03/2023

每个 API 管理服务实例都保留一个配置数据库，该数据库包含关于服务实例的配置和元数据的信息。可以通过在 Azure 门户中更改设置、使用 Azure PowerShell 或 Azure CLI 等 Azure 工具或进行 REST API 调用对服务实例进行更改。除了这些方法，还可以使用 Git 管理服务实例配置，从而为以下场景tight支持：

配置版本控制 - 下载并存储不同版本的服务配置
批量配置更改 - 在本地存储库中对服务配置的多个部分进行更改，然后通过单个操作将更改集成回服务器
熟悉的 Git 工具链和工作流 - 使用熟悉的 Git 工具链和工作流

下图显示配置 API 管理服务实例的不同方式的概述。

Diagram that compares ways to configure Azure API Management.

使用 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 支持团队。

可用性

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。

访问服务中的 Git 配置

在 Azure 门户中导航到自己的 API 管理实例。
在左侧菜单中的“部署和基础结构”下方，选择“存储库”。

Screenshot showing how to access Git configuration for API Management.

将服务配置保存到 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 管理服务实例。

注意

以下实体不包含在 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 的描述，对应于 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 - 电子邮件模板的正文。

后续步骤

有关管理服务实例的其他方法的信息，请参阅：