如何使用 Git 保存和配置 API 管理服务How to save and configure your API Management service configuration using Git

每个 API 管理服务实例都保留一个配置数据库,该数据库包含关于服务实例的配置和元数据的信息。Each API Management service instance maintains a configuration database that contains information about the configuration and metadata for the service instance. 可能通过在 Azure 门户中更改设置、使用 PowerShell cmdlet 或进行 REST API 调用对服务实例进行更改。Changes can be made to the service instance by changing a setting in the Azure portal, using a PowerShell cmdlet, or making a REST API call. 除了这些方法,还可以使用 Git 管理服务实例配置,从而支持下列服务管理方案:In addition to these methods, you can also manage your service instance configuration using Git, enabling service management scenarios such as:

  • 配置版本控制 - 下载和存储不同版本的服务配置Configuration versioning - download and store different versions of your service configuration
  • 批量配置更改 - 通过单个操作,在本地存储库中对服务配置的多个部分进行更改,并将更改集成回服务器Bulk configuration changes - make changes to multiple parts of your service configuration in your local repository and integrate the changes back to the server with a single operation
  • 熟悉的 Git 工具链和工作流 - 使用已经熟悉的 Git 工具和工作流Familiar Git toolchain and workflow - use the Git tooling and workflows that you are already familiar with

下图显示配置 API 管理服务实例的不同方式的概述。The following diagram shows an overview of the different ways to configure your API Management service instance.

Git 配置

使用 Azure 门户、PowerShell cmdlet 或 REST API 对服务进行更改时,即表示正在使用 https://{name}.management.azure-api.cn 终结点管理服务配置数据库,如图右侧所示。When you make changes to your service using the Azure portal, PowerShell cmdlets, or the REST API, you are managing your service configuration database using the https://{name}.management.azure-api.cn endpoint, as shown on the right side of the diagram. 图左侧说明了如何针对位于 https://{name}.scm.azure-api.cn 的服务使用 Git 和 Git 存储库管理服务配置。The left side of the diagram illustrates how you can manage your service configuration using Git and Git repository for your service located at https://{name}.scm.azure-api.cn.

以下步骤概述了如何使用 Git 管理 API 管理服务实例。The following steps provide an overview of managing your API Management service instance using Git.

  1. 访问服务中的 Git 配置Access Git configuration in your service
  2. 将服务配置数据库保存到 Git 存储库Save your service configuration database to your Git repository
  3. 将 Git 存储库克隆到本地计算机Clone the Git repo to your local machine
  4. 将最新的存储库提取到本地计算,并将更改提交并推送回存储库Pull the latest repo down to your local machine, and commit and push changes back to your repo
  5. 将更改从存储库部署到服务配置数据库中Deploy the changes from your repo into your service configuration database

本文介绍如何启用和使用 Git 管理服务配置,并提供 Git 存储库中的文件和文件夹的参考。This article describes how to enable and use Git to manage your service configuration and provides a reference for the files and folders in the Git repository.

可用性Availability

重要

此功能在 API 管理的“高级”、“标准”、“基本”和“开发人员”层中可用。This feature is available in the Premium, Standard, Basic and Developer tiers of API Management.

访问服务中的 Git 配置Access Git configuration in your service

若要查看和配置 Git 配置设置,可单击“安全” 菜单并导航到“配置存储库” 选项卡。To view and configure your Git configuration settings, you can click the Security menu and navigate to the Configuration repository tab.

启用 Git

重要

未定义为“命名值”的任何机密都将保存在存储库中,并将保留在其历史记录中,直到禁用并重新启用 Git 访问。Any secrets that are not defined as Named Values will be stored in the repository and will remain in its history until you disable and re-enable Git access. “命名值”提供了管理所有 API 配置和策略的常量字符串值(包括机密)的安全位置,因此无需将它们直接存储在策略声明中。Named Values provide a secure place to manage constant string values, including secrets, across all API configuration and policies, so you don't have to store them directly in your policy statements. 有关详细信息,请参阅如何在 Azure API 管理策略中使用命名值For more information, see How to use Named Values in Azure API Management policies.

有关使用 REST API 启用或禁用 Git 访问的信息,请参阅使用 REST API 启用或禁用 Git 访问For information on enabling or disabling Git access using the REST API, see Enable or disable Git access using the REST API.

将服务配置保存到 Git 存储库To save the service configuration to the Git repository

克隆存储库之前的第一个步骤是将服务配置的当前状态保存到存储库。The first step before cloning the repository is to save the current state of the service configuration to the repository. 单击“保存到存储库” 。Click Save to repository.

在确认屏幕上进行任何所需的更改,并单击“确定” 保存。Make any desired changes on the confirmation screen and click Ok to save.

片刻后配置已保存,并显示存储库的配置状态,包括上次配置更改和服务配置与存储库之间上次同步的日期和时间。After a few moments the configuration is saved, and the configuration status of the repository is displayed, including the date and time of the last configuration change and the last synchronization between the service configuration and the repository.

将配置保存到存储库后,可以克隆它。Once the configuration is saved to the repository, it can be cloned.

有关使用 REST API 执行此操作的信息,请参阅使用 REST API 提交配置快照For information on performing this operation using the REST API, see Commit configuration snapshot using the REST API.

将存储库克隆到本地计算机To clone the repository to your local machine

若要克隆存储库,需要存储库的 URL、用户名和密码。To clone a repository, you need the URL to your repository, a user name, and a password. 若要获取用户名和其他凭据,请单击页面顶部附近的“访问凭据” 。To get user name and other credentials, click on Access credentials near the top of the page.

若要生成密码,先确保“到期” 设置为所需的到期日期和时间,然后单击“生成” 。To generate a password, first ensure that the Expiry is set to the desired expiration date and time, and then click Generate.

重要

记下此密码。Make a note of this password. 离开此页面后,不会再次显示该密码。Once you leave this page the password will not be displayed again.

以下示例使用 Windows 版 Git 中的 Git Bash 工具,但你可以使用熟悉的任何 Git 工具。The following examples use the Git Bash tool from Git for Windows but you can use any Git tool that you are familiar with.

使用 Azure 门户提供的命令,在所需文件夹中打开 Git 工具并运行以下命令以将 Git 存储库克隆到本地计算机。Open your Git tool in the desired folder and run the following command to clone the git repository to your local machine, using the command provided by the Azure portal.

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

出现提示时,输入用户名和密码。Provide the user name and password when prompted.

如果收到任何错误,请尝试将 git clone 命令修改为包含用户名和密码,如以下示例所示。If you receive any errors, try modifying your git clone command to include the user name and password, as shown in the following example.

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

如果这样会产生错误,请尝试对命令的密码部分进行 URL 编码。If this provides an error, try URL encoding the password portion of the command. 执行此操作的一个快速方法是打开 Visual Studio,并在“即时窗口” 中发出以下命令。One quick way to do this is to open Visual Studio, and issue the following command in the Immediate Window. 若要打开“即时窗口” ,请在 Visual Studio 中打开任意解决方案或项目(或创建新的空白控制台应用程序),并从“调试” 菜单中依次选择“Windows” 、“即时” 。To open the Immediate Window, open any solution or project in Visual Studio (or create a new empty console application), and choose Windows, Immediate from the Debug menu.

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

将编码密码与用户名和存储库位置一起用于构造 Git 命令。Use the encoded password along with your user name and repository location to construct the git command.

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

克隆存储库后,可在本地文件系统中查看和处理它。Once the repository is cloned, you can view and work with it in your local file system. 有关详细信息,请参阅本地 Git 存储库的文件和文件夹结构参考For more information, see File and folder structure reference of local Git repository.

使用最新服务实例配置更新本地存储库To update your local repository with the most current service instance configuration

如果在 Azure 门户中或使用 REST API 对 API 管理服务实例进行更改,必须先将这些更改保存到存储库,然后才能使用最新更改更新本地存储库。If you make changes to your API Management service instance in the Azure portal or using the REST API, you must save these changes to the repository before you can update your local repository with the latest changes. 要执行此操作,请单击 Azure 门户中“配置存储库” 选项卡上的“将配置保存到存储库” ,然后在本地存储库中发布以下命令。To do this, click Save configuration to repository on the Configuration repository tab in the Azure portal, and then issue the following command in your local repository.

git pull

运行 git pull 之前,请确保自己位于本地存储库的文件夹中。Before running git pull ensure that you are in the folder for your local repository. 如果刚刚完成 git clone 命令,则必须通过运行如下命令将目录更改为存储库。If you have just completed the git clone command, then you must change the directory to your repo by running a command like the following.

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

将更改从本地存储库推送到服务器存储库To push changes from your local repo to the server repo

若要将更改从本地存储库推送到服务器存储库,必须提交更改,然后将它们推送到服务器存储库。To push changes from your local repository to the server repository, you must commit your changes and then push them to the server repository. 若要提交更改,请打开 Git 命令工具,切换到本地存储库的目录,然后发出以下命令。To commit your changes, open your Git command tool, switch to the directory of your local repository, and issue the following commands.

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

若要将所有提交推送到服务器,请运行以下命令。To push all of the commits to the server, run the following command.

git push

将任何服务配置更改部署到 API 管理服务实例To deploy any service configuration changes to the API Management service instance

将本地更改提交并推送到服务器存储库后,可将它们部署到 API 管理服务实例。Once your local changes are committed and pushed to the server repository, you can deploy them to your API Management service instance.

有关使用 REST API 执行此操作的信息,请参阅使用 REST API 将 Git 更改部署到配置数据库For information on performing this operation using the REST API, see Deploy Git changes to configuration database using the REST API.

本地 Git 存储库的文件和文件夹结构参考File and folder structure reference of local Git repository

本地 Git 存储库中的文件和文件夹包含有关服务实例的配置信息。The files and folders in the local git repository contain the configuration information about the service instance.

项目Item 说明Description
根 api-management 文件夹root api-management folder 包含服务实例的顶级配置Contains top-level configuration for the service instance
apis 文件夹apis folder 包含服务实例中的 API 的配置Contains the configuration for the apis in the service instance
groups 文件夹groups folder 包含服务实例中的组的配置Contains the configuration for the groups in the service instance
policies 文件夹policies folder 包含服务实例中的策略Contains the policies in the service instance
portalStyles 文件夹portalStyles folder 包含服务实例中的开发人员门户自定义的配置Contains the configuration for the developer portal customizations in the service instance
products 文件夹products folder 包含服务实例中产品的配置Contains the configuration for the products in the service instance
templates 文件夹templates folder 包含服务实例中电子邮件模板的配置Contains the configuration for the email templates in the service instance

每个文件夹都可包含一个或多个文件,并且在某些情况下可包含一个或多个文件夹,例如,每个 API、产品或组对应一个文件夹。Each folder can contain one or more files, and in some cases one or more folders, for example a folder for each API, product, or group. 每个文件夹内的文件都特定于文件夹名称所述的实体类型。The files within each folder are specific for the entity type described by the folder name.

文件类型File type 目的Purpose
jsonjson 关于相应实体的配置信息Configuration information about the respective entity
htmlhtml 关于实体的说明,通常显示在开发人员门户中Descriptions about the entity, often displayed in the developer portal
xmlxml 策略语句Policy statements
csscss 用于开发人员门户自定义的样式表Style sheets for developer portal customization

可在本地文件系统中创建、删除、编辑和管理这些文件,并将更改部署回 API 管理服务实例。These files can be created, deleted, edited, and managed on your local file system, and the changes deployed back to your API Management service instance.

备注

以下实体不包含在 Git 存储库中,并且无法使用 Git 进行配置。The following entities are not contained in the Git repository and cannot be configured using Git.

根 api-management 文件夹Root api-management folder

api-management 文件夹包含 configuration.json 文件,该文件包含采用以下格式的关于服务器实例的顶级信息。The root api-management folder contains a configuration.json file that contains top-level information about the service instance in the following format.

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

前四个设置(RegistrationEnabledUserRegistrationTermsUserRegistrationTermsEnabledUserRegistrationTermsConsentRequired)映射到“安全” 部分中的“标识” 选项卡上的以下设置。The first four settings (RegistrationEnabled, UserRegistrationTerms, UserRegistrationTermsEnabled, and UserRegistrationTermsConsentRequired) map to the following settings on the Identities tab in the Security section.

标识设置Identity setting 映射到Maps to
RegistrationEnabledRegistrationEnabled 是否存在用户名和密码标识提供者Presence of Username and password identity provider
UserRegistrationTermsUserRegistrationTerms “用户注册使用条款” 文本框Terms of use on user signup textbox
UserRegistrationTermsEnabledUserRegistrationTermsEnabled “在注册页上显示使用条款” 复选框Show terms of use on signup page checkbox
UserRegistrationTermsConsentRequiredUserRegistrationTermsConsentRequired “需要同意” 复选框Require consent checkbox
RequireUserSigninEnabledRequireUserSigninEnabled “将匿名用户重定向到登录页” 复选框Redirect anonymous users to sign-in page checkbox

接下来的四个设置(DelegationEnabledDelegationUrlDelegatedSubscriptionEnabledDelegationValidationKey)映射到“安全” 部分中的“委派” 选项卡上的以下设置。The next four settings (DelegationEnabled, DelegationUrl, DelegatedSubscriptionEnabled, and DelegationValidationKey) map to the following settings on the Delegation tab in the Security section.

委派设置Delegation setting 映射到Maps to
DelegationEnabledDelegationEnabled “委派登录和注册” 复选框Delegate sign-in & sign-up checkbox
DelegationUrlDelegationUrl “委派终结点 URL” 文本框Delegation endpoint URL textbox
DelegatedSubscriptionEnabledDelegatedSubscriptionEnabled “委派产品订阅” 复选框Delegate product subscription checkbox
DelegationValidationKeyDelegationValidationKey “委派验证密钥” 文本框Delegate Validation Key textbox

最后的设置 $ref-policy 映射到服务实例的全局策略声明文件。The final setting, $ref-policy, maps to the global policy statements file for the service instance.

apis 文件夹apis folder

apis 文件夹针对服务实例中每个 API 都包括了一个文件夹,其中包含以下项。The apis folder contains a folder for each API in the service instance, which contains the following items.

  • apis\<api name>\configuration.json - 这是 API 的配置,包含关于后端服务 URL 和操作的信息。apis\<api name>\configuration.json - this is the configuration for the API and contains information about the backend service URL and the operations. 这是使用 export=trueapplication/json 格式调用获取特定 API 时会返回的相同信息。This is the same information that would be returned if you were to call Get a specific API with export=true in application/json format.
  • apis\<api name>\api.description.html - 这是 API 的说明,对应于 API 实体description 属性。apis\<api name>\api.description.html - this is the description of the API and corresponds to the description property of the API entity.
  • apis\<api name>\operations\ - 此文件夹包含映射到 API 中的操作的 <operation name>.description.html 文件。apis\<api name>\operations\ - this folder contains <operation name>.description.html files that map to the operations in the API. 每个文件包含 API 中单个操作的说明,该说明映射到 REST API 中操作实体description 属性。Each file contains the description of a single operation in the API, which maps to the description property of the operation entity in the REST API.

groups 文件夹groups folder

groups 文件夹包含适用于服务实例中定义的每个组的文件夹。The groups folder contains a folder for each group defined in the service instance.

  • groups\<group name>\configuration.json - 这是组的配置。groups\<group name>\configuration.json - this is the configuration for the group. 这是调用获取特定组操作时会返回的相同信息。This is the same information that would be returned if you were to call the Get a specific group operation.
  • groups\<group name>\description.html - 这是组的说明,对应于组实体description 属性。groups\<group name>\description.html - this is the description of the group and corresponds to the description property of the group entity.

policies 文件夹policies folder

policies 文件夹包含服务实例的策略声明。The policies folder contains the policy statements for your service instance.

  • policies\global.xml - 包含在服务实例的全局范围内定义的策略。policies\global.xml - contains policies defined at global scope for your service instance.
  • policies\apis\<api name>\ - 如果有任何在 API 范围内定义的策略,它们包含在此文件夹中。policies\apis\<api name>\ - if you have any policies defined at API scope, they are contained in this folder.
  • policies\apis\<api name>\<operation name>\ 文件夹 - 如果有任何在操作范围内定义的策略,它们以映射到每个操作的策略声明的 <operation name>.xml 文件形式包含在此文件夹中。policies\apis\<api name>\<operation name>\ folder - if you have any policies defined at operation scope, they are contained in this folder in <operation name>.xml files that map to the policy statements for each operation.
  • policies\products\ - 如果有任何在产品范围内定义的策略,它们包含在此文件夹中,该文件夹包含映射到每个产品的策略声明的 <product name>.xml 文件。policies\products\ - if you have any policies defined at product scope, they are contained in this folder, which contains <product name>.xml files that map to the policy statements for each product.

portalStyles 文件夹portalStyles folder

portalStyles 文件夹包含用于服务实例的开发人员门户自定义的配置和样式表。The portalStyles folder contains configuration and style sheets for developer portal customizations for the service instance.

  • portalStyles\configuration.json - 包含开发人员门户使用的样式表名称portalStyles\configuration.json - contains the names of the style sheets used by the developer portal
  • portalStyles\<style name>.css - 每个 <style name>.css 文件都包含开发人员门户的样式(默认为 Preview.cssProduction.css)。portalStyles\<style name>.css - each <style name>.css file contains styles for the developer portal (Preview.css and Production.css by default).

products 文件夹products folder

products 文件夹包含适用于服务实例中定义的每个产品的文件夹。The products folder contains a folder for each product defined in the service instance.

  • products\<product name>\configuration.json - 这是产品的配置。products\<product name>\configuration.json - this is the configuration for the product. 这是调用获取特定产品操作时会返回的相同信息。This is the same information that would be returned if you were to call the Get a specific product operation.
  • products\<product name>\product.description.html - 这是产品的说明,对应于 REST API 中产品实体description 属性。products\<product name>\product.description.html - this is the description of the product and corresponds to the description property of the product entity in the REST API.

模板templates

templates 文件夹包含服务实例的电子邮件模板配置。The templates folder contains configuration for the email templates of the service instance.

  • <template name>\configuration.json - 这是电子邮件模板的配置。<template name>\configuration.json - this is the configuration for the email template.
  • <template name>\body.html - 这是电子邮件模板的正文。<template name>\body.html - this is the body of the email template.

后续步骤Next steps

有关管理服务实例的其他方法的信息,请参阅:For information on other ways to manage your service instance, see: