Azure API 管理
Azure DevOps
Azure Pipelines
GitHub
APIOps 是一種方法，可將 GitOps 和 DevOps 的概念套用至 API 部署。 此架構示範如何使用 APIOps CLI 來擷取、審查並透過 Git 基礎工作流程推廣 Azure API 管理 設定。 使用此方法管理 API 生命週期、提升 API 品質，並維護可稽核變更的紀錄。
架構
下圖說明了高階 APIOps CLI 配置推廣工作流程。 Teams 在 Git 中審查 API 管理產物，接著持續整合與持續交付（CI/CD）管線將核准的配置推廣到目標 API 管理環境。
下載此架構的Visio檔案。
Workflow
API 管理設定從擷取現有的 API 管理設定開始，或撰寫相容 CLI 的 API 管理工件。 操作流程從上述任一工件輸入開始。 這兩條路徑都會導致相同的拉取請求、驗證、核准與部署流程：
（A） 優先擷取： API 操作員會對現有的 API Management 實例執行
apiops extract，在其本地 Git 檢出分支中建立 API Management 工件檔案。 操作員利用這些產物來提出基準線或擷取核准的配置變更。（B） 程式碼優先： API 開發者在其本地 Git 結帳分支中撰寫或更新 APIOps 相容的 CLI 規範、資訊檔案、政策及相關 API 管理產物。
對任一輸入使用以下生命週期：
建立組態變更。 在初始擷取或以程式碼優先方式建立成品並簽入後，API 組態存放庫會成為 API Management 組態成品的權威事實來源。 該儲存庫維護每次部署的版本歷史與稽核紀錄。 要進行變更，API 操作員或開發者會在 API 組態倉庫中從受保護分支建立分支，並對該 API 進行一項邏輯變更。
檢視並驗證變更。 操作員或開發者會開啟拉取請求，將他們的分支合併到受保護的分支中。 API 合約、政策及 API 管理設定的必要擁有者與審查者會審查拉取請求。 CI/CD 系統執行以下檢查與測試：
- API 規格檢查
- 針對已核准合約的破壞性變更偵測
- 規格與存放庫內容的安全性掃描
- API 測試，用以驗證預期行為、認證、政策效果及後端相依性
這些檢查不需要 Microsoft 的工具。 團隊會使用符合組織支援、安全及授權要求的合適工具。
核准不可變更的部署輸入。 必要的擁有者或審查者會核准提取要求，而已獲授權的存放庫維護者則會在所有必要的檢查與審查皆通過後，合併經審查的變更。 合併後不可變更的提交紀錄及其受保護分支成品，會成為該儲存庫可稽核的可信依據。
團隊保護受保護的倉庫分支免於直接推送，敏感目標需環境或服務連線核准，並使用獨立的最低權限身份進行擷取與發佈。 他們會記錄已核准的提交內容，以及其提取要求、審查與驗證結果，以確保可稽核性。
預覽部署過程。 CI/CD 管線會針對已核准的提交執行
apiops publish --dry-run，使用相同的目標和 覆寫檔案，但不進行發佈。 發布核准者會審查試跑將建立、更新、刪除或略過的資源。 團隊將成功的試演視為部署門檻，而非自動化 API 測試的替代方案。發表並推廣。 在試跑通過驗證後，CI/CD 管線會用
apiops publish來發佈相同的審查提交。 針對多個環境，平台團隊會維持共用構件的穩定性，並使用經過審查的覆寫組態檔來設定後端 URL、資源 ID 和機密參照等值。 團隊會在生產前透過非生產階段推動提交，並防止多條管線同時寫入同一目標。Note
這項設定支援 工作區子項覆寫，但在發佈時不會套用這些覆寫。 發佈僅對工作區容器本身套用覆寫。 不要依賴工作區子覆蓋來推廣環境專屬的工作空間 API、後端、命名值或其他子資源。 驗證這些資源的替代推廣方式，或暫緩推廣，直到 未套用工作區範圍的覆寫屬性 這個已知問題獲得解決。
部署後進行驗證與對帳。 發佈後，營運團隊會執行自動化煙霧與回歸測試，監控 API 管理與後端健康狀況，並將部署結果與核准提交進行比較。 團隊透過拉取請求調查並解決意外變更，而非直接編輯製作環境。
若 API 操作員直接在 API Management 中進行已核准的緊急變更，則該操作員必須在 Git 的工作複本中執行擷取作業，檢閱並在其分支上提交構件變更、推送該分支，然後開啟 Pull Request。 必須的擁有者或審查者審查並批准拉取請求，且授權的倉庫維護者必須將其合併，以確保倉庫保持權威性。
元件
API 管理 是一種管理服務，為後端服務建立一致的 API 閘道。 在此架構中，它提供 APIOps CLI 擷取的原始組態，以及 CLI 發布核准 API 定義、政策、產品、診斷、命名值及其他支援配置的目標環境。
APIOps CLI 是一個開源專案，提供支持有主見的 APIOps 方法的工具。 在此架構中，它能將 API Management 設定擷取為工件檔案，將工件發佈至 API 管理，並能架構 CI/CD 工作流程。
Git 儲存庫儲存 API 管理產物，並在適用時儲存 API 合約。 它提供審核歷史及核准的管線部署真相來源。
CI/CD 系統透過使用工作負載身份或其他支援的非互動憑證來執行驗證、擷取與發布。 在此架構中，GitHub Actions 或 Azure Pipelines 定義 CI/CD 工作流程。
替代方案
你可以根據工作負載的功能與非功能需求，用其他 Azure 服務或方法取代或增強此架構。 請考慮下列替代方案和取捨。
Bicep 或 Terraform 和 APIOps 可以服務同一解決方案的不同部分。 擁有 API 管理組態與基礎架構的團隊，可以使用基礎架構即程式碼（IaC）來配置 API 管理服務及其支援基礎架構，並使用相同的 IaC 管線來管理 API 管理的配置。 當基礎架構與配置同時變更與部署，且參數能表達不同環境差異時，選擇此方法。
當 API 定義、政策及相關設定擁有獨立擁有者或獨立於服務基礎架構的發佈生命週期時，請使用 APIOps 模式。 APIOps 也適合當你需要擷取現有配置、審查以 API 為核心的產物，或在多個環境或 API 管理實例間推廣相同核准的配置時。 更頻繁的 API 與政策變更，或更多環境，能提升這個專用工作流程的價值。
這些因素沒有固定的門檻。 決策主要依據所有權、審查需求及部署邊界。 對於較小且變動率低的 API 資產，建議先從手動拉取請求工作流程開始，並在建立倉庫基線與核准流程後，才加入擷取排程或部署自動化。
案例詳細資料
APIOps 利用版本控制來管理 API，並建立對 API 定義、政策、產品、診斷及其他 API 管理設定變更的稽核軌跡。 更早且更頻繁地檢視變更，有助於團隊在部署前識別與 API 標準的偏差。 隨著越來越多 API 採用相同流程，團隊能提升其 API 資產間的一致性。
此工作流程將 API 管理設定部署至 API 管理實例。 它不會部署 API 後端、應用程式運算或資料資源、網路或 API 管理服務基礎設施。 使用分開且受治理的 IaC 管線和應用程式管線來部署這些層。
此解決方案有助於團隊：
- 維護環境與 API 管理實例的概覽。
- 追蹤 API 與政策的關鍵變更。
- 為已核准的部署建立稽核軌跡。
- 協調來自儲存庫外部的已核准變更。
選擇文物來源與所有權
在自動化部署之前，請從下列成品進入儲存庫的方式中選擇，並決定在此之前由誰擁有這些成品：
- 先摘錄： 擷取一個已知良好的 API Management 實例，建立初始產出物基線。 在將資料庫視為真實來源之前，請先檢視已輸入的產出產物。
- 程式碼優先： 請保留 API 合約，例如 OpenAPI 描述，與應用程式來源或 APIOps 儲存庫一同說明。 定義誰負責將該合約轉換成管線發布的 API 管理產物。 用非生產環境的 API 管理實例驗證預期的匯入與產物工作流程。 不要假設任意的原始碼配置可以直接被 CLI 消耗。
- 共同責任： 確定 API 開發者、平台營運者，或兩者是否擁有對政策、產品、診斷、命名值及 API 定義的變更。 在基準獲得認可後，將每一項變更都透過同一個儲存庫和審查流程處理。
潛在使用案例
開發及管理 API 的組織，包括透過 API 管理公開單一 API 的組織。
高度管制的產業，如保險、銀行、金融和政府，需要可追溯的審查與部署紀錄。
考量
這些考量實現了 Azure Well-Architected 框架的支柱，這是一套指導原則，用以提升工作負載的品質。 如需詳細資訊，請參閱 Well-Architected Framework。
Reliability
可靠性有助於確保您的應用程式可以符合您對客戶的承諾。 欲了解更多資訊，請參閱 可靠性設計審查清單。
對於非破壞性的 API 變更，請使用 API Management 版本 部署並測試非最新版本，再讓它成為最新版本。 如果在發佈後驗證失敗，請將先前的修訂版本還原為目前版本。 使用 API 版本來破壞合約變更，讓現有消費者能繼續使用早期版本。
將 API 管理的設定變更與每個 API 後端的部署策略協調一致。 還原 APIOps commit 時，只會還原該 commit 所代表的設定。 它不會復原不相容或不可用的後端。 記錄每個已知良好部署的 APIOps 提交、API 管理版本及後端發布。 在非生產環境中測試完整的回滾程序，包括政策、命名值、秘密參考、相依性及後端相容性。
安全性
安全保障能防止蓄意攻擊及珍貴資料與系統被濫用。 如需詳細資訊，請參閱 安全性的設計檢閱檢查清單。
使用儲存庫與管線作為應用 API 管理變更的正常路徑。 開發者和操作者不需要對生產環境 API 管理實例有持久寫入權限。 僅在必要時且有限時間內，才准許提升進入權。 將任何因此產生的變更整合到儲存庫中。
請使用以下機制來保護儲存 API 管理產物的 Git 倉庫：
- 提取要求審查： 保護部署組態且要求由適當審查者進行審查的分支。
- 認證隔離： 如果可用，請優先使用聯合工作負載身分識別。 將環境特定的秘密存放在核准的秘密儲存庫或儲存庫環境中，而非工件或管線檔案中。
- 提交完整性： 要求已簽署的提交，以驗證提交的來源。 設定分支保護以防止強制推送與分支刪除，要求多重身份驗證以允許使用者批准或合併變更，並保留提交與拉取請求的部署歷史。
- 產出物審查：檢查擷取輸出和發布輸入中是否含有機密資訊、遮蔽標記，以及非預期的特定環境值。 驗證變更不會擴大 API 存取範圍或削弱政策。
將 APIOps CLI 作為存放庫相依性來管理。 將 package.json 中的 @azure-tools/apiops-cli 釘選為經過測試的版本，提交鎖定檔，然後使用 npm ci。 在啟用生產管線前，請先檢視產生的身份設定、變數、觸發條件及保護規則。
成本優化
成本優化著重於減少不必要的費用，並提升營運效率的方式。 如需詳細資訊，請參閱 成本優化的設計檢閱檢查清單。
APIOps CLI 是開源軟體，但此情境會對 API 管理實例及所選的原始碼控制與 CI/CD 平台產生成本。 由於 API 管理價格會依地區、層級、單位數量、容量模型、可用性區域或多區域配置及使用量而有所不同，因此不會提供單一固定估算。 CI/CD 收費也取決於 Runner 類型、包含的分鐘數、並行數、儲存空間和保留期限。
在 Azure 價格計算器中建立特定情境估算，並在架構決策時記錄以下假設：
| 估計輸入 | 待記錄的假設 |
|---|---|
| API 管理區域 | 每個開發、測試、暫存及生產實例的部署區域。 |
| 等級與容量 | 每個環境的分級或 v2 層級、單元數量或閘道器數量，以及營運時間。 |
| Resiliency | 任何可用區或其他區域的部署，包括各位置中的單元。 |
| 使用量型費用 | 預期的請求或操作，以及任何適用的工作空間、自架閘道、網路、監控或資料傳輸費用。 |
| CI/CD 平台 | GitHub 代管、自架設或 Azure Pipelines 代理程式。 預期管線運行量、持續時間、並行性、儲存，以及日誌或文物保留。 |
| 原始碼控制與授權 | 用戶數量以及任何付費的 GitHub 或 Azure DevOps 計畫功能。 |
請使用目前的 API 管理定價細節 來選擇適用的計費模式。 關於 CI/CD 與原始碼控制的假設，請參閱 Azure DevOps 定價與 GitHub 定價。 匯出或擷取計算機估算、貨幣、定價日期及所有假設，讓審核者能重現並更新。 部署前及區域、層級、單位數量、環境或管線使用情況變更前，請重新計算。
卓越營運
卓越營運涵蓋部署應用程式並使其持續在生產環境中執行的作業流程。 如需詳細資訊，請參閱 卓越營運的設計檢閱檢查清單。
APIOps 使部署可重複進行，並建立提交歷史以供變更後分析。 標記或以其他方式記錄每個環境收到的提交，保留管線日誌，並在部署後監控 API Management 實例及相關 API。
對於多個環境，透過開發、分期和生產推廣同一審查過的產物承諾。 僅對必須因環境而異的值使用環境覆寫，並以審查產出物時相同的謹慎態度檢查這些檔案。 工作區子層覆寫不會在發佈時套用，因此不要用於環境提升。 在事故發生前，先測試回滾程序。 Git 還原仍需驗證並進行受控發佈以恢復 API 管理。
CLI 提供 init、 extract、 publish 和 指令，並且可以搭建 GitHub Actions 或 Azure DevOps 管線。
請參考 APIOps CLI 文件中的指令細節。
安全地從舊版 APIOps 工具組遷移
如果你的 APIOps 流程使用舊有的 APIOps 工具包，請計劃升級。 這種做法使用獨立的 Extractor 與 Publisher 二進位檔及管線範本。 APIOps CLI 使用單一 Node.js CLI，但其工件格式設計上與現有工具包工件相容。 把遷移當作受控的切換，而不是原地生產升級。
標記已知良好的工具包產物與流程，並保留現有發行商作為回滾選項。 不要在同一部署中更換舊版發行商並引入新發行商。
在遷移分支中，使用最新的 APIOps CLI 版本，並執行
apiops init時不使用--force。 該指令偵測衝突檔案並退出，而非覆蓋它們。 比較並有意識地整合生成的管線、識別指引、篩選器及覆寫檔案。將產件與
apiops publish --dry-run目標環境的覆蓋對照非生產環境的 API 管理實例使用。 檢視 CLI 會建立、更新或刪除的資源。 測試一次受控發佈，並驗證已部署的 API、原則、命名值和相依性。不要在遷移或升級設計中使用工作區子項覆寫設定，因為這些設定在發佈時不會套用。 驗證受影響子資源的替代提升方式，或延後其遷移，直到 未套用工作區範圍覆寫屬性 的已知問題獲得解決為止。
切換時，允許只有一個發佈者能寫入 API Management 實例。 在啟用 CLI 發佈者之前，先停用舊有發佈者觸發器。 部署已審查的提交版本，並監看結果。 在新工作流程完成成功發布週期之前，請保留已標記的工具包管線與工件基線。
關於相容性細節及逐指令遷移範例，請參見 APIOps 工具包的遷移。
部署此情境
請參考 APIOps CLI GitHub 倉庫中的 APIOps CLI 文件。 從非生產環境的 API 管理實例開始，並依照目前的 APIOps CLI 發布指引開始。 想開始使用非生產環境，請參閱 如何使用 APIOps CLI 管理 API 管理設定。
參與者
本文由 Microsoft 維護。 以下貢獻者撰寫了這篇文章。
主要作者：
若要查看非公開的 LinkedIn 個人檔案，請登入 LinkedIn。