使用 DevOps 和 CI/CD 發佈 API

適用於：所有 API 管理 層

透過企業中的 API 策略價值，採用 DevOps 持續整合 (CI) 和持續部署 (CD) 技術已成為 API 開發的重要層面。 本文討論您為了採用 DevOps 原則來管理 API 必須做出的決策。

API DevOps 包含三個部分：

以下討論 API DevOps 管線的每個部分。

API 定義

API 開發人員藉由提供規格、設定 (例如記錄、診斷和後端設定) 以及要套用至 API 的原則，來寫入 API 定義。 API 定義提供在 Azure APIM 服務上佈建 API 所需的資訊。 規格可能是根據以標準為基礎的 API 規格 (例如WSDL、OpenAPI 或 GraphQL)，或者可以使用 Azure Resource Manager (ARM) API (例如，描述 API 和作業的 ARM 範本) 來定義。 API 定義會隨著時間而變更，而且應該視為「原始程式碼」。 確定 API 定義會儲存在原始程式碼控制下，並在採用之前進行適當的檢閱。

有數個工具可以協助產生 API 定義：

• Azure APIOps 工具組提供建置在 Git 原始程式碼控制系統 (例如 GitHub 或 Azure Repos) 基礎之上的工作流程。 使用「擷取器」來產生 API 定義，然後由「發行者」套用至目標 APIM 服務。 APIOps 目前支援 REST 和 GraphQL API。
• dotnet-apim 工具會將格式正確的 YAML 定義轉換成 ARM 範本，以供稍後部署。 此工具著重於 REST API。
• Terraform 是 Azure Resource Manager 在 Azure 中設定資源的替代方案。 您可以建立 Terraform 組態 (與原則一起)，以建立 ARM 範本的相同方式實作 API。

您也可以針對編輯器 (例如 Visual Studio Code) 使用 IDE 型工具來產生定義 API 所需的成品。 例如，Visual Studio Code Marketplace 上有超過 30 個適用於編輯 OpenAPI 規格檔案的外掛程式。 您也可以使用程式碼產生器來建立成品。 CADL 語言可讓您輕鬆地建立高階建置組塊，然後將其編譯成標準 API 定義格式，例如 OpenAPI。

API 核准

產生 API 定義之後，開發人員會提交 API 定義以供檢閱和核准。 如果使用 Git 型原始程式碼控制系統 (例如 GitHub 或 Azure Repos)，則可以透過提取要求完成提交。 提取要求會通知其他人已對 API 定義建議的變更。 確認核准閘道之後，核准者會將提取要求合併到主要存放庫，以表示 API 定義可以部署到生產環境。 提取要求程序可讓開發人員修復核准程序期間發現的任何問題。

GitHub 和 Azure Repos 都允許設定在提交提取要求時執行的核准管線。 您可以將核准管線設定為執行下列工具：

• API 規格 Linter，例如 Spectral，以確保定義符合組織所需的 API 標準。
• 使用 openapi-diff 之類的工具進行中斷性變更偵測。
• 安全性稽核和評量工具。 OWASP 會維護工具清單以進行安全性掃描。
• 自動化 API 測試架構，例如 Newman，這是 Postman 集合的測試執行器。

注意

Azure API 必須符合一組嚴格的指導方針，您可用來作為您自己的 API 指導方針起點。 有一個強制執行指導方針的 Spectral 組態。

一旦執行自動化工具，API 定義就會透過肉眼檢閱。 工具不會攔截所有問題。 人類檢閱者可確保 API 定義符合 API 的組織準則，包括遵循安全性、隱私權和一致性指導方針。

API 發行

API 定義會透過發行管線發佈至 APIM 服務。 用來發佈 API 定義的工具取決於用來產生 API 定義的工具：

• 如果使用 Azure APIOps 工具組，則工具組會包含將 API 定義寫入目標服務的發行者。
• 如果使用 dotnet-apim，則 API 定義會以 ARM 範本表示。 工作可供 Azure Pipelines 和 GitHub Actions 部署 ARM 範本使用。
• 如果使用 Terraform，CLI 工具會在您的服務上部署 API 定義。 Azure Pipelines 和 GitHub Actions 有可用的工作。

我可以使用其他原始程式碼控制和 CI/CD 系統嗎？

是。 所述程序會使用任何原始程式碼控制系統 (雖然 APIOps 不需要原始程式碼控制系統是以 git 為基礎)。 同樣地，只要可以藉由簽入和執行命令列工具 (可與 Azure 通訊) 來觸發 CI/CD 平台，您就可以使用此平台。

最佳作法

沒有適用於針對發佈 API 設定 DevOps 管線的業界標準，而且沒有任何提及的工具可在所有情況中運作。 不過，我們發現大部分的情況涵蓋在使用下列工具和服務的組合下：

• Azure Repos 會將 API 定義儲存在 git 存放庫中。
• Azure Pipelines 會執行自動化 API 核准和 API 發行程序。
• Azure APIOps 工具組提供用於發佈 API 的工具和工作流程。

我們已在客戶部署中看到最大的成功，並建議下列做法：

• 為原始程式碼控制系統設定 GitHub 或 Azure Repos。 此選項也會決定您的管線執行器選擇。 GitHub 可以使用 Azure Pipelines 或 GitHub Actions，而 Azure Repos 必須使用 Azure Pipelines。
• 為每個 API 開發人員設定 Azure APIM 服務，讓他們可以開發 API 定義以及 API 服務。 建立服務時，請使用使用量或開發人員 SKU。
• 使用原則片段來減少開發人員針對每個 API 所需撰寫的新原則。
• 使用具名值和後端來確保原則可通用，且可套用至任何 APIM 執行個體。
• 使用 Azure APIOps 工具組從開發人員服務擷取運作中的 API 定義。
• 設定在每個提取要求上執行的 API 核准程序。 API 核准程序應包含中斷性變更偵測、Lint 分析和自動化 API 測試。
• 使用 Azure APIOps 工具組發行者，將 API 發佈至生產 APIM 服務。

如需如何使用 APIOps 設定和執行 CI/CD 部署管線的詳細資訊，請參閱 Azure 架構中心中的使用 APIOps 自動化 API 部署。

參考資料

• Azure DevOps Services 包括 Azure Repos和 Azure Pipelines。
• Azure APIOps 工具組提供 APIM DevOps 的工作流程。
• Spectral 提供 OpenAPI 規格的 Linter。
• openapi-diff 提供 OpenAPI v3 定義的中斷性變更偵測器。
• Newman 提供 Postman 集合的自動化測試執行器。