API 控管

  • 5 分鐘

API 控管的定義是，在所有組織 API 間大規模定義及套用標準、原則和程序的做法。 API 中心可讓您實現此目標，方式如下：

  • 追蹤 API 中繼資料，包括 API 標題、描述、版本、定義和部署。 此外，您可以指定自己的自訂 API 中繼資料 (例如即時網站資訊、原始檔控制存放庫等)，以追蹤對組織具重要性的中繼資料 (如先前的課程模組所示)。
  • 確保所有 API 的設計都符合組織 API 設計理念
  • 確保能及時偵測具有中斷性變更的 API 版本，以便能順暢地推出及告知 API 取用者

在本單元中，我們將了解 API 中心如何讓您設定 API 大規模控管。

必要條件

若要使用 API 中心控管 API，您必須：

  1. 安裝 Azure CLI。
  2. 安裝 Azure Developer CLI (azd)。
  3. 在您的訂用帳戶中註冊事件方格資源提供者。 如果您需要註冊事件方格資源提供者，請參閱訂閱 Azure 事件方格的合作夥伴所發佈的事件。

API 設計一致性

API 平台小組常負責定義一組適用於 API 產生者的指導方針。 API 中心可讓您使用 Spectral 開放原始碼 Lint 分析引擎定義規則，以編寫 API 指導方針。 根據預設，API 中心會隨附 Spectral 規則，但您可以自行建置規則，或運用廣大的開放原始碼規則集社群。 每當有 API 定義上傳時，API 中心就會使用隨附的規則集執行 Spectral Linter，以檢查 API 定義是否符合規則。 系統會產生可在 API 中心檢視的 API 合規性報告。

若要為組織設定 API 設計一致性：

  1. 複製 GitHub 存放庫， 並在 Visual Studio Code 中開啟。

  2. 將目錄變更為存放庫中的 APICenter-Analyzer 資料夾。

  3. 在 resources/rulesets 資料夾中，您可以找到 oas.yaml 檔案。 此檔案會反映您目前的 API 樣式指南，並且可根據您的組織需要和要求進行修改。

  4. 在 Azure Developer CLI 和 Azure CLI 中，使用下列命令進行驗證：

    azd auth login

az login

  5. 執行下列命令，將 Lint 分析基礎結構部署至您的 Azure 訂用帳戶。

    azd up

  6. 依照提示提供必要的部署資訊和設定，例如環境名稱和 API 中心名稱。 如需詳細資訊，請參閱使用 Azure Developer CLI (azd) 執行範例。

    注意

    部署可能需要幾分鐘的時間。

  7. 部署完成後，在 Azure 入口網站中瀏覽至您的 API 中心。 在左側功能表中選取 [事件]>[事件訂閱]，以檢視已建立的事件訂閱。

此時您可以將 API 定義檔上傳至 API 中心，以觸發事件訂閱及執行 Lint 分析引擎。

此螢幕擷取畫面顯示 Azure 入口網站中的 API 分析合規性報告。

左移 API 控管

最成功的控管計畫絕對少不了開發人員本身。 藉由套用傳統的左移原則，API 平台小組可確保 API 產生者會確切了解他們在開發週期初期發佈 API 所須符合的需求。 這樣可以減少後續在開發週期補救不合規 API 的需求，而節省寶貴的開發時間。

Visual Studio Code 的 API 中心延伸模組可讓 API 產生者於 API 建置期間直接在 Visual Studio Code 中執行 API 設計一致性檢查。 此外，API 產生者可以使用中斷性變更偵測功能，偵測可能會導致 API 取用者聊天中斷的變更。

Visual Studio Code 中的 API 設計一致性

API 中心延伸模組可與 Spectral 整合，後者為支援 OpenAPI 和自訂規則集的 JSON/YAML Linter。 此延伸模組可讓開發人員嚴格遵循隨附或建議的 API 樣式指南，確保跨不同小組所開發的所有 API 間保有一致性。

注意

您必須安裝 API 中心和 Spectral 延伸模組，才能使用此功能。

若要啟用：

  1. 使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API 中心：設定作用中 API 樣式指南，然後按 Enter 鍵。
  2. 選取其中一個隨附的預設規則，或者，如果您的組織已有可用的樣式指南，請使用 [選取本機檔案] 或 [輸入遠端 URL]，在 Visual Studio Code 中指定作用中規則集。 按 Enter 鍵。 此螢幕擷取畫面顯示在 VS Code 上設定 API 樣式指南的選項

在設定作用中 API 樣式指南後，若開啟任何 OpenAPI 或 AsyncAPI 型規格檔案，都會在 Visual Studio Code 中觸發本機 Lint 分析作業。 結果會內嵌顯示於編輯器中，以及 [問題] 視窗 ([檢視] > [問題] 或 Ctrl+Shift+M)。此螢幕擷取畫面顯示 VS Code 上的 Lint 分析檢查結果

偵測 Visual Studio Code 中的中斷性變更

交付會中斷取用者生產工作流程的 API 版本，會導致不可靠和失去信任。 API 中心延伸模組使用 Optic，可讓開發人員輕鬆比較任兩個 API 版本，並在部署之前偵測對 API 導入的任何中斷性變更。

注意

您必須安裝 Optic 才能使用這項功能。 使用下列命令進行安裝。

*npm install -g @useoptic/optic*

接著，

  1. 使用 Ctrl+Shift+P 鍵盤快速鍵開啟命令選擇區。 輸入 Azure API 中心：偵測中斷性變更，然後按 Enter 鍵。
  2. 選取要比較的第一個 API 規格文件。 有效選項包括位於 API 中心、本機檔案或 Visual Studio Code 作用中編輯器中的 API 規格。
  3. 選取要比較的第二個 API 規格文件。 有效選項包括位於 API 中心、本機檔案或 Visual Studio Code 作用中編輯器中的 API 規格。

Visual Studio Code 會在兩個 API 規格之間開啟差異檢視。 任何中斷性變更都會內嵌顯示於編輯器中，以及 [問題] 視窗 ([檢視] > [問題] 或 Ctrl+Shift+M)。此螢幕擷取畫面顯示在 VS Code 上偵測中斷性變更的情形