將 API 資產從 Git 存儲庫同步到 Azure API 中心

本文說明如何將 Git 儲存庫與 Azure API Center 整合，以自動將 skills、agents 和 MCP 伺服器 等 API 資產同步到您的 API 清查中。 透過連接 Git 倉庫，你可以保持 API 中心庫存的即時更新，而不必手動註冊或更新每個資產。

當你整合 Git 倉庫時：

• 你的 API 中心會 建立一個環境 ，將儲存庫視為資產來源。
• API Center 會定期將資產資訊從資料庫同步到您的 API 中心庫存。

Prerequisites

• API 中心。 如果你還沒有 API 中心，請參考快速入門的「 建立 API 中心」。

• 一個包含你想要同步資產的 Git 倉庫。

• 對於非公開倉庫，則需使用個人存取權杖（PAT）來存取資料庫。 PAT 必須擁有適當的權限才能讀取儲存庫內容。 要為 GitHub 建立 PAT，請參見 「建立細粒度個人存取權杖」。

• 用於儲存 PAT 的 Azure Key Vault (若使用 PAT 進行存取)。 如果你需要建立金鑰保險庫，請參考 快速入門：使用 Azure portal 建立金鑰金庫。 要在金鑰庫中新增或管理秘密，至少需要擁有 金鑰庫秘密官（金鑰保存庫 Secrets Officer ）角色或同等權限。

• For Azure CLI：

  • 在 Azure Cloud Shell 中使用 Bash 環境。 欲了解更多資訊，請參見開始使用 Azure Cloud Shell。

    

  • 若要在本地執行 CLI 參考命令，請安裝 Azure CLI。 如果你是在 Windows 或 macOS 上運行，可以考慮在 Docker 容器中執行 Azure CLI。 如需詳細資訊，請參閱 如何在 Docker 容器中執行 Azure CLI。

    • 如果您使用的是本機安裝，請使用 az login 命令，透過 Azure CLI 來登入。 請遵循您終端機上顯示的步驟，完成驗證程序。 如需其他登入選項，請參閱 使用 Azure CLI 向 Azure 進行驗證。

    • 出現提示時，請在第一次使用時安裝 Azure CLI 延伸模組。 如需擴充功能的詳細資訊，請參閱 使用和管理 Azure CLI 的擴充功能。

    • 執行 az version 以尋找已安裝的版本和相依程式庫。 若要升級至最新版本，請執行 az upgrade。

  Note

  你可以在這篇文章中用 PowerShell 或 bash shell 執行 Azure CLI 指令範例。 若因變數語法不同而有需要，已為兩個 Shell 程式提供了個別的命令範例供參考。

Store PAT in Azure Key Vault

如果你的 Git 儲存庫是私人的，請手動上傳並安全地儲存一個 PAT 到 Azure Key Vault，以取得儲存庫存取權限。 當你將 Git 倉庫與 API 中心整合時，設定整合時使用這個秘密。

如需詳細資訊，請參閱快速入門：使用 Azure 入口網站從 Azure Key Vault 設定及擷取祕密。

如果你不需要設定 PAT，請繼續整合 Git 儲存庫。

為你的 API 中心設定一個管理身份

你的 API 中心會使用受管理身份來驗證 Azure Key Vault 並取得存取 Git 倉庫所需的 PAT。 以下程序說明如何手動設定 API 中心的管理身份，並賦予其存取金鑰庫所需的權限。

如果你沒有設定管理身份，API Center 可以在你整合 Git 倉庫時自動幫你設定。

在此案例中，您的 API 中心會使用 受控識別 來存取 Azure 資源。 根據您的需求，啟用系統指派的或一個或多個使用者指派的受管理的身分識別。

下列範例示範如何使用 Azure 入口網站 或 Azure CLI 來啟用系統指派的受控識別。 概括而言，設定步驟與使用者指派的受控識別類似。

Portal

1. 在 入口網站，前往你的 API 中心。
2. 在側邊欄選單中，在 安全性下，選擇 受管理身份。
3. 選取 [系統指派]，然後將狀態設定為 [開啟]。
4. 選取 [儲存]。

Azure CLI

使用以下指令 az apic update 在 API 管理中心設定系統指派身份。 替換 API 中心和資源群組的名稱：

az apic update --name <api-center-name> --resource-group <resource-group-name> --identity '{"type": "SystemAssigned"}'

將 金鑰保存庫 祕密使用者角色指派給受控識別

為了允許匯入資產，請將你的 API 中心的管理身份指定為 Azure 金鑰庫中的 金鑰保存庫 Secrets 使用者 角色。 您可以使用入口網站或 Azure CLI。

Portal

1. 在 入口網站裡，前往你的鑰匙庫。
2. 在側邊欄選單中，選擇存取控制（IAM）。
3. 選擇 + 新增角色指派。
4. 在 [新增角色指派] 窗格上設定值，如下所示：
   1. 在 Role 標籤中，選擇 金鑰保存庫 Secrets User。
   2. 在成員索引標籤的指派存取權給 - 選取受控識別>+ 選取成員。
   3. 在 [ 選取受控識別 ] 頁面上，選取您在上一節中新增之 API 中心的系統指派受控識別。 按一下 ‹選取›。
   4. 選擇 檢閱 + 指派。

Azure CLI

1. 取得該識別的主體識別碼。 針對系統指派身分識別，請使用 az apic show 命令。

   #! /bin/bash
   apicObjID=$(az apic show --name <api-center-name> \
       --resource-group <resource-group-name> \
       --query "identity.principalId" --output tsv)
   

   # Formatted for PowerShell
   $apicObjID=$(az apic show --name <api-center-name> `
       --resource-group <resource-group-name> `
       --query "identity.principalId" --output tsv)
   

2. 使用 az keyvault show 命令取得金鑰保存庫的資源識別碼。

   #! /bin/bash
   kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

   # Formatted for PowerShell
   $kvID=$(az keyvault show --name <kv-name> --resource-group <resource-group-name> --query "id" --output tsv)
   

3. 使用 az role assignment create 命令，將金鑰保存庫中的 金鑰保存庫 祕密使用者角色指派給受控識別。

   #! /bin/bash
   scope="${kvID:1}"
   
   az role assignment create \
       --role "Key Vault Secrets User" \
       --assignee-object-id $apicObjID \
       --assignee-principal-type ServicePrincipal \
       --scope $scope 
   

   # Formatted for PowerShell
   $scope=$apimID.substring(1)
   
   az role assignment create `
       --role "Key Vault Secrets User" `
       --assignee-object-id $apicObjID `
       --assignee-principal-type ServicePrincipal `
       --scope $scope 
   

整合 Git 儲存庫

要整合 Git 儲存庫：

1. 在 Azure 入口網站，前往你的 API 中心。

2. 在側邊欄選單中，選擇 平台>整合。

3. 選擇 + 新整合，並選擇 從 Git 儲存庫。

4. 在 整合你的 Git 儲存庫時，請輸入以下資訊：

   Field	說明
   設定 Git 儲存庫原始碼
   儲存庫網址	輸入包含資產檔案的 Git 倉庫的網址。 可選擇性地指定分支與子資料夾（例如）。 https://github.com/<org>/<repo>/tree/main/skills
   Git 提供者	選擇提供者（例如 ，GitHub）。
   資產類型配置	API Center 會設定一個預設的 技能 資產類型，並搭配檔案模式 **/skill.md。 選擇 + 新增資產類型 以新增一個或多個資產類型以同步。
   個人存取權杖 （PAT）	如果你在 Azure Key Vault 中儲存了 PAT，請按一下 選擇 以瀏覽 金鑰保存庫 機密。 如果你沒有手動設定管理身份以存取金鑰保險庫的秘密，也可以選擇 自動設定管理身份並指派權限 。
   整合細節	接受產生的連結識別碼，或為整合連結提供自訂 ID。
   環境細節
   環境標題	輸入一個友善的儲存庫環境名稱（例如 Git 倉庫）。
   識別	輸入環境資源名稱（例如 git-repository）。
   環境類型	選擇環境類型（例如 生產環境）。
   說明	可選擇性地加入環境描述。
   資產細節
   生命週期	選擇從儲存庫同步的資產的生命週期階段（例如設計）。

   

5. 選擇創建。

入口網站會將環境新增至你的 API 中心。 入口網站會將倉庫中的資產加入 API 中心的庫存，在庫存>資產頁面上。 你可以透過列表中的連結圖示來識別連結資產。

相關內容

• 註冊並發掘你的 API 技能庫
• Azure API Center 中的關鍵概念