PageRenderTime 61ms CodeModel.GetById 27ms RepoModel.GetById 0ms app.codeStats 0ms

/articles/api-management/api-management-configuration-repository-git.md

https://gitlab.com/yeah568/azure-content
Markdown | 302 lines | 193 code | 109 blank | 0 comment | 0 complexity | 9c8818f5d817117e28a780a6f6592e7e MD5 | raw file
  1. <properties
  2. pageTitle="How to save and configure your API Management service configuration using Git"
  3. description="Learn how to save and configure your API Management service configuration using Git."
  4. services="api-management"
  5. documentationCenter=""
  6. authors="steved0x"
  7. manager="erikre"
  8. editor=""/>
  9. <tags
  10. ms.service="api-management"
  11. ms.workload="mobile"
  12. ms.tgt_pltfrm="na"
  13. ms.devlang="na"
  14. ms.topic="article"
  15. ms.date="05/25/2016"
  16. ms.author="sdanie"/>
  17. # How to save and configure your API Management service configuration using Git
  18. >[AZURE.IMPORTANT] Git configuration for API Management is currently in preview. It is functionally complete, but is in preview because we are actively seeking feedback on this feature. It is possible that we may make a breaking change in response to customer feedback, so we recommend not depending on the feature for use in production environments. If you have any feedback or questions, please let us know at `apimgmt@microsoft.com`.
  19. Each API Management service instance maintains a configuration database that contains information about the configuration and metadata for the service instance. Changes can be made to the service instance by changing a setting in the publisher portal, using a PowerShell cmdlet, or making a REST API call. In addition to these methods, you can also manage your service instance configuration using Git, enabling service management scenarios such as:
  20. - Configuration versioning - download and store different versions of your service configuration
  21. - 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
  22. - Familiar Git toolchain and workflow - use the Git tooling and workflows that you are already familiar with
  23. The following diagram shows an overview of the different ways to configure your API Management service instance.
  24. ![Git configure][api-management-git-configure]
  25. When you make changes to your service using the publisher portal, PowerShell cmdlets, or the REST API, you are managing your service configuration database using the `https://{name}.management.azure-api.net` endpoint, as shown on the right side of the diagram. 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.net`.
  26. The following steps provide an overview of managing your API Management service instance using Git.
  27. 1. Enable Git access in your service
  28. 2. Save your service configuration database to your Git repository
  29. 3. Clone the Git repo to your local machine
  30. 4. Pull the latest repo down to your local machine, and commit and push changes back to your repo
  31. 5. Deploy the changes from your repo into your service configuration database
  32. 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.
  33. ## To enable Git access
  34. You can quickly view the status of your Git configuration by viewing the Git icon in the upper-right corner of the publisher portal. In this example, Git access has not yet been enabled.
  35. ![Git status][api-management-git-icon-enable]
  36. To view and configure your Git configuration settings, you can either click the Git icon, or click the **Security** menu and navigate to the **Configuration repository** tab.
  37. ![Enable GIT][api-management-enable-git]
  38. To enable Git access, check the **Enable Git access** checkbox.
  39. After a moment the change is saved and a confirmation message is displayed. Note that Git icon has changed to color to indicate that Git access is enabled and the status message now indicates that there are unsaved changes to the repository. This is because the API Management service configuration database has not yet been saved to the repository.
  40. ![Git enabled][api-management-git-enabled]
  41. >[AZURE.IMPORTANT] Any secrets that are not defined as properties will be stored in the repository and will remain in its history until you disable and re-enable Git access. Properties 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. For more information, see [How to use properties in Azure API Management policies](api-management-howto-properties.md).
  42. For information on enabling or disabling Git access using the REST API, see [Enable or disable Git access using the REST API](https://msdn.microsoft.com/library/dn781420.aspx#EnableGit).
  43. ## To save the service configuration to the Git repository
  44. The first step before cloning the repository is to save the current state of the service configuration to the repository. Click **Save configuration to repository**.
  45. ![Save configuration][api-management-save-configuration]
  46. Make any desired changes on the confirmation screen and click **Ok** to save.
  47. ![Save configuration][api-management-save-configuration-confirm]
  48. 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.
  49. ![Configuration status][api-management-configuration-status]
  50. Once the configuration is saved to the repository, it can be cloned.
  51. For information on performing this operation using the REST API, see [Commit configuration snapshot using the REST API](https://msdn.microsoft.com/library/dn781420.aspx#CommitSnapshot).
  52. ## To clone the repository to your local machine
  53. To clone a repository, you need the URL to your repository, a user name, and a password. The user name and URL are displayed near the top of the **Configuration repository** tab.
  54. ![Git clone][api-management-configuration-git-clone]
  55. The password is generated at the bottom of the **Configuration repository** tab.
  56. ![Generate password][api-management-generate-password]
  57. To generate a password, first ensure that the **Expiry** is set to the desired expiration date and time, and then click **Generate Token**.
  58. ![Password][api-management-password]
  59. >[AZURE.IMPORTANT] Make a note of this password. Once you leave this page the password will not be displayed again.
  60. The following examples use the Git Bash tool from [Git for Windows](http://www.git-scm.com/downloads) but you can use any Git tool that you are familiar with.
  61. 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 publisher portal.
  62. git clone https://bugbashdev4.scm.azure-api.net/
  63. Provide the user name and password when prompted.
  64. If you receive any errors, try modifying your `git clone` command to include the user name and password, as shown in the following example.
  65. git clone https://username:password@bugbashdev4.scm.azure-api.net/
  66. If this provides an error, try URL encoding the password portion of the command. One quick way to do this is to open Visual Studio, and issue the following command in the **Immediate Window**. 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.
  67. ?System.NetWebUtility.UrlEncode("password from publisher portal")
  68. Use the encoded password along with your user name and repository location to construct the git command.
  69. git clone https://username:url encoded password@bugbashdev4.scm.azure-api.net/
  70. Once the repository is cloned you can view and work with it in your local file system. For more information, see [File and folder structure reference of local Git repository](#file-and-folder-structure-reference-of-local-git-repository).
  71. ## To update your local repository with the most current service instance configuration
  72. If you make changes to your API Management service instance in the publisher 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. To do this, click **Save configuration to repository** on the **Configuration repository** tab in the publisher portal, and then issue the following command in your local repository.
  73. git pull
  74. Before running `git pull` ensure that you are in the folder for your local repository. 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.
  75. cd bugbashdev4.scm.azure-api.net/
  76. ## To push changes from your local repo to the server repo
  77. To push changes from your local repository to the server repository, you must commit your changes and then push them to the server repository. To commit your changes, open your Git command tool, switch to the directory of your local repository, and issue the following commands.
  78. git add --all
  79. git commit -m "Description of your changes"
  80. To push all of the commits to the server, run the following command.
  81. git push
  82. ## To deploy any service configuration changes to the API Management service instance
  83. Once your local changes are committed and pushed to the server repository, you can deploy them to your API Management service instance.
  84. ![Deploy][api-management-configuration-deploy]
  85. For information on performing this operation using the REST API, see [Deploy Git changes to configuration database using the REST API](https://msdn.microsoft.com/library/dn781420.aspx#DeployChanges).
  86. ## File and folder structure reference of local Git repository
  87. The files and folders in the local git repository contain the configuration information about the service instance.
  88. | Item | Description |
  89. |------------------------- |--------------------------------------------------------------------------------------------|
  90. | root api-management folder | Contains top-level configuration for the service instance |
  91. | apis folder | Contains the configuration for the apis in the service instance |
  92. | groups folder | Contains the configuration for the groups in the service instance |
  93. | policies folder | Contains the policies in the service instance |
  94. | portalStyles folder | Contains the configuration for the developer portal customizations in the service instance |
  95. | products folder | Contains the configuration for the products in the service instance |
  96. | templates folder | Contains the configuration for the email templates in the service instance |
  97. 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.
  98. | File type | Purpose |
  99. |-----------|------------------------------------------------------------------------|
  100. | json | Configuration information about the respective entity |
  101. | html | Descriptions about the entity, often displayed in the developer portal |
  102. | xml | Policy statements |
  103. | css | Style sheets for developer portal customization |
  104. These files can be created, deleted, edited, and managed on your local file system, and the changes deployed back to the your API Management service instance.
  105. >[AZURE.NOTE] The following entities are not contained in the Git repository and cannot be configured using Git.
  106. >
  107. >- Users
  108. >- Subscriptions
  109. >- Properties
  110. >- Developer portal entities other than styles
  111. ### Root api-management folder
  112. The root `api-management` folder contains a `configuration.json` file that contains top-level information about the service instance in the following format.
  113. {
  114. "settings": {
  115. "RegistrationEnabled": "True",
  116. "UserRegistrationTerms": null,
  117. "UserRegistrationTermsEnabled": "False",
  118. "UserRegistrationTermsConsentRequired": "False",
  119. "DelegationEnabled": "False",
  120. "DelegationUrl": "",
  121. "DelegatedSubscriptionEnabled": "False",
  122. "DelegationValidationKey": ""
  123. },
  124. "$ref-policy": "api-management/policies/global.xml"
  125. }
  126. The first four settings (`RegistrationEnabled`, `UserRegistrationTerms`, `UserRegistrationTermsEnabled`, and `UserRegistrationTermsConsentRequired`) map to the following settings on the **Identities** tab in the **Security** section.
  127. | Identity setting | Maps to |
  128. |--------------------------------------|-------------------------------------------------------|
  129. | RegistrationEnabled | **Redirect anonymous users to sign-in page** checkbox |
  130. | UserRegistrationTerms | **Terms of use on user signup** textbox |
  131. | UserRegistrationTermsEnabled | **Show terms of use on signup page** checkbox |
  132. | UserRegistrationTermsConsentRequired | **Require consent** checkbox |
  133. ![Identity settings][api-management-identity-settings]
  134. The next four settings (`DelegationEnabled`, `DelegationUrl`, `DelegatedSubscriptionEnabled`, and `DelegationValidationKey`) map to the following settings on the **Delegation** tab in the **Security** section.
  135. | Delegation setting | Maps to |
  136. |------------------------------|--------------------------------------------|
  137. | DelegationEnabled | **Delegate sign-in & sign-up** checkbox |
  138. | DelegationUrl | **Delegation endpoint URL** textbox |
  139. | DelegatedSubscriptionEnabled | **Delegate product subscription** checkbox |
  140. | DelegationValidationKey | **Delegate Validation Key** textbox |
  141. ![Delegation settings][api-management-delegation-settings]
  142. The final setting, `$ref-policy`, maps to the global policy statements file for the service instance.
  143. ### apis folder
  144. The `apis` folder contains a folder for each API in the service instance which contains the following items.
  145. - `apis\<api name>\configuration.json` - this is the configuration for the API and contains information about the backend service URL and the operations. This is the same information that would be returned if you were to call [Get a specific API](https://msdn.microsoft.com/library/azure/dn781423.aspx#GetAPI) with `export=true` in `application/json` format.
  146. - `apis\<api name>\api.description.html` - this is the description of the API and corresponds to the `description` property of the [API entity](https://msdn.microsoft.com/library/azure/dn781423.aspx#EntityProperties).
  147. - `apis\<api name>\operations\` - this folder contains `<operation name>.description.html` files that map to the operations in the API. Each file contains the description of a single operation in the API which maps to the `description` property of the [operation entity](https://msdn.microsoft.com/library/azure/dn781423.aspx#OperationProperties) in the REST API.
  148. ### groups folder
  149. The `groups` folder contains a folder for each group defined in the service instance.
  150. - `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](https://msdn.microsoft.com/library/azure/dn776329.aspx#GetGroup) operation.
  151. - `groups\<group name>\description.html` - this is the description of the group and corresponds to the `description` property of the [group entity](https://msdn.microsoft.com/library/azure/dn776329.aspx#EntityProperties).
  152. ### policies folder
  153. The `policies` folder contains the policy statements for your service instance.
  154. - `policies\global.xml` - contains policies defined at global scope for your service instance.
  155. - `policies\apis\<api name>\` - if you have any policies defined at API scope, they are contained in this folder.
  156. - `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.
  157. - `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.
  158. ### portalStyles folder
  159. The `portalStyles` folder contains configuration and style sheets for developer portal customizations for the service instance.
  160. - `portalStyles\configuration.json` - contains the names of the style sheets used by the developer portal
  161. - `portalStyles\<style name>.css` - each `<style name>.css` file contains styles for the developer portal (`Preview.css` and `Production.css` by default).
  162. ### products folder
  163. The `products` folder contains a folder for each product defined in the service instance.
  164. - `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](https://msdn.microsoft.com/library/azure/dn776336.aspx#GetProduct) operation.
  165. - `products\<product name>\product.description.html` - this is the description of the product and corresponds to the `description` property of the [product entity](https://msdn.microsoft.com/library/azure/dn776336.aspx#Product) in the REST API.
  166. ### templates
  167. The `templates` folder contains configuration for the [email templates](api-management-howto-configure-notifications.md) of the service instance.
  168. - `<template name>\configuration.json` - this is the configuration for the email template.
  169. - `<template name>\body.html` - this is the body of the email template.
  170. ## Next steps
  171. For information on other ways to manage your service instance, see:
  172. - Manage your service instance using the following PowerShell cmdlets
  173. - [Service deployment PowerShell cmdlet reference](https://msdn.microsoft.com/library/azure/mt619282.aspx)
  174. - [Service management PowerShell cmdlet reference](https://msdn.microsoft.com/library/azure/mt613507.aspx)
  175. - Manage your service instance in the publisher portal
  176. - [Manage your first API](api-management-get-started.md)
  177. - Manage your service instance using the REST API
  178. - [API Management REST API reference](https://msdn.microsoft.com/library/azure/dn776326.aspx)
  179. ## Watch a video overview
  180. > [AZURE.VIDEO configuration-over-git]
  181. [api-management-enable-git]: ./media/api-management-configuration-repository-git/api-management-enable-git.png
  182. [api-management-git-enabled]: ./media/api-management-configuration-repository-git/api-management-git-enabled.png
  183. [api-management-save-configuration]: ./media/api-management-configuration-repository-git/api-management-save-configuration.png
  184. [api-management-save-configuration-confirm]: ./media/api-management-configuration-repository-git/api-management-save-configuration-confirm.png
  185. [api-management-configuration-status]: ./media/api-management-configuration-repository-git/api-management-configuration-status.png
  186. [api-management-configuration-git-clone]: ./media/api-management-configuration-repository-git/api-management-configuration-git-clone.png
  187. [api-management-generate-password]: ./media/api-management-configuration-repository-git/api-management-generate-password.png
  188. [api-management-password]: ./media/api-management-configuration-repository-git/api-management-password.png
  189. [api-management-git-configure]: ./media/api-management-configuration-repository-git/api-management-git-configure.png
  190. [api-management-configuration-deploy]: ./media/api-management-configuration-repository-git/api-management-configuration-deploy.png
  191. [api-management-identity-settings]: ./media/api-management-configuration-repository-git/api-management-identity-settings.png
  192. [api-management-delegation-settings]: ./media/api-management-configuration-repository-git/api-management-delegation-settings.png
  193. [api-management-git-icon-enable]: ./media/api-management-configuration-repository-git/api-management-git-icon-enable.png