如何使用 Git 儲存和設定 API 管理服務組態

發行項
03/28/2024

適用於：開發人員 |基本 |標準 |進階版

每個 API 管理服務執行個體會維護組態資料庫，包含服務執行個體的組態和中繼資料的相關資訊。可以對服務執行個體進行變更，方法是使用 Azure PowerShell 或 Azure CLI，或進行 REST API 呼叫等 Azure 工具，變更 Azure 入口網站中的設定。除了這些方法，您也可以使用 Git 管理服務執行個體組態，啟用下列案例：

組態版本 - 下載並儲存不同版本的服務組態
大量的組態變更 - 對本機儲存機制中服務組態的多個部分進行變更，並且使用單一作業將變更整合回伺服器
熟悉的 Git 工具鏈和工作流程 - 使用您已熟悉的 Git 工具和工作流程

下圖顯示設定您的 API 管理服務執行個體的不同方式的概觀。

比較設定 Azure API 管理方式的圖表。

當您使用 Azure 入口網站、Azure PowerShell 或 Azure CLI，或 REST API 等 Azure 工具對服務進行變更時，您會使用 https://{name}.management.azure-api.net 端點管理服務組態資料庫，如圖表右側所示。圖表左側說明如何針對位於 https://{name}.scm.azure-api.net的服務，使用 Git 和 Git 儲存機制管理服務組態。

下列步驟提供使用 Git 管理 API 管理服務執行個體的概觀。

存取服務中的 Git 組態
將您的服務組態資料庫儲存至您的 Git 儲存機制
將 Git 儲存機制複製到本機電腦
將最新的儲存機制提取至您的本機電腦，認可並且將變更推送回您的儲存機制
從您的儲存機制將變更部署至您的服務組態資料庫

本文說明如何啟用及使用 Git 來管理您的服務組態，並提供 Git 儲存機制中檔案和資料夾的參考。

重要

此功能的設計目的在於與中小型 API 管理服務組態配合使用，例如匯出大小小於 10 MB 或實體少於 10,000 個的組態。處理 Git 命令時，如果服務包含大量實體 (產品、API、作業、結構描述等)，可能遇到非預期的失敗。如果您遇到這類失敗，請減少服務設定的大小，然後再試一次。如需協助，請連絡 Azure 支援。

存取服務中的 Git 組態

在 Azure 入口網站中瀏覽至您的 API 管理執行個體。
在左側功能表中的 [部署和基礎結構] 下，選擇 [存放庫]。

顯示如何存取 API 管理 Git 設定的螢幕快照。

將服務組態儲存至 Git 存放庫

警告

任何未定義為「具名值」的密碼，都將儲存在存放庫中，並保留在其記錄中。「具名值」提供安全的地方來管理所有 API 設定和原則的常數字串值 (包括密碼)，因此，不需要直接儲存在原則陳述式中。如需詳細資訊，請參閱在 Azure API 管理原則中使用具名值。

複製存放庫之前，將服務組態的目前狀態儲存至存放庫。

在 [存放庫] 分頁上，選取 [儲存至存放庫]。
在確認畫面上進行任何所需的變更，例如儲存組態的分支名稱，然後選取 [儲存]。

儲存組態一段時間後，儲存機制的組態狀態隨即顯示，包括最後組態變更和上次同步處理服務組態和儲存機制的日期與時間。

一旦組態儲存至儲存機制，就可以複製。

如需使用 REST API 儲存服務組態的資訊，請參閱租用戶設定 - 儲存。

取得存取認證

若要複製存放庫，除了存放庫的 URL 之外，您還需要使用者名稱和密碼。

在 [存放庫] 分頁上，選取靠近分頁頂端的 [存取認證]。
記下 [存取認證] 分頁上提供的使用者名稱。
若要產生密碼，請先確定已將 [到期] 設為所需的到期日期和時間，然後選取 [產生]。

重要

記下此密碼。一旦您離開此頁面，就不會再次顯示密碼。

將存放庫複製到本機電腦

下列範例會使用來自適用於 Windows 的 Git 的 Git Bash 工具，但是您可以使用任何您熟悉的 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 儲存機制的檔案和資料夾結構參考。

使用最新的服務執行個體組態更新本機存放庫

如果您在 Azure 入口網站中或使用其他 Azure 工具變更您的 APIM 服務執行個體，您必須先將這些變更儲存至存放庫，才能使用最新的變更來更新本機存放庫。

若要使用 Azure 入口網站儲存變更，請在 APIM 執行個體的 [存放庫] 索引標籤上選取 [儲存至存放庫]。

然後，更新您的本機存放庫：

請確認您是位於本機存放庫的資料夾中。如果您已完成 git clone 命令，則必須執行類似下列的命令，將目錄變更為您的存放庫。
```
cd {name}.scm.azure-api.net/
```
在本機存放庫的資料夾中，發出下列命令。
```
git pull
```

將變更從您的本機存放庫推送至伺服器存放庫

若要將變更從本機儲存機制推送至伺服器儲存機制，必須認可您的變更，然後再將其推送至伺服器儲存機制。若要認可變更，請開啟您的 Git 命令工具，切換至您的本機儲存機制的目錄，然後發出下列命令。

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

若要將所有認可推送至伺服器，請執行下列命令。

git push

將服務組態變更部署至 APIM 服務執行個體

一旦您的本機變更被認可並且推送至伺服器儲存機制，您可以將它們部署到您的 API 管理服務執行個體。

在 Azure 入口網站中瀏覽至您的 API 管理執行個體。
在左側功能表中的 [部署和基礎結構] 下，選擇 [存放庫]>[部署至 APIM]。
在 [部署存放庫組態] 分頁上，輸入包含所需組態變更的分支名稱，並選擇性地選取 [移除已刪除產品的訂閱]。選取 [儲存]。

如需使用 REST API 執行這項作業的資訊，請參閱租用戶設定 - 部署。

本機 Git 儲存機制的檔案和資料夾結構參考

本機 Git 儲存機制中的檔案和資料夾包含服務執行個體的相關設定資訊。

項目	說明
根 api 管理資料夾	包含服務執行個體的最上層組態
apiReleases 資料夾	包含服務執行個體中 API 版本的組態
apis 資料夾	包含服務執行個體中 API 的組態
apiVersionSets 資料夾	包含服務執行個體中 API 版本集的組態
後端資料夾	包含服務執行個體中後端資源的組態
群組資料夾	包含服務執行個體中群組的組態
原則資料夾	包含服務執行個體中的原則
portalStyles 資料夾	包含服務執行個體中開發人員入口網站自訂的組態
portalTemplates 資料夾	包含服務執行個體中開發人員入口網站範本的組態
產品資料夾	包含服務執行個體中產品的組態
範本資料夾	包含服務執行個體中電子郵件範本的組態

每個資料夾可以包含一或多個檔案，在某些情況下可以包含一或多個資料夾，例如每個 API、產品或群組的資料夾。每個資料夾中的檔案是特定於資料夾名稱所描述的實體類型。

檔案類型	目的
json	個別實體的組態資訊
html	實體的相關描述，通常顯示於開發人員入口網站
xml	Policy statements
css	開發人員入口網站自訂的樣式表

可以在您的本機檔案系統上建立、刪除、編輯和管理這些檔案，並將變更部署回您的 API 管理服務執行個體。

注意

下列實體不包含在 Git 儲存機制，因此無法使用 Git 來設定。

使用者
訂用帳戶
具名值
樣式和範本以外的開發人員入口網站實體
原則片段

根 api 管理資料夾

根 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	文字方塊
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\<group name>\configuration.json - 群組的組態。此資訊與當您呼叫取得特定群組作業時傳回的資訊相同。
groups\<group name>\description.html - 這是群組的說明，並會對應至群組實體的 description 屬性。

原則資料夾

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\<product name>\configuration.json - 這是產品的組態。此資訊與當您呼叫取得特定產品作業時傳回的資訊相同。
products\<product name>\product.description.html - 這是產品的說明，並會對應至 REST API 中產品實體的 description 屬性。

templates

templates 資料夾包含服務執行個體的電子郵件範本的組態。

<template name>\configuration.json電子郵件範本的組態。
<template name>\body.html - 這是電子郵件範本的主體。

下一步

如需管理您的服務執行個體的其他方法的詳細資訊，請參閱︰