從 Azure API 管理將 API 匯入至 API 中心

本文說明如何使用 Azure CLI，將 API 從 Azure API 管理執行個體匯入 (新增) 至您的 API 中心。將 API 從 API 管理新增至 API 詳細目錄，有助於讓開發人員、API 方案經理，以及組織中的其他專案關係人探索及存取 API。

本文會說明使用 Azure CLI 從 APIM 將 API 新增至 API 中心的兩個選項：

選項 1：使用 az apim api export 命令從 API 管理實例匯出 API 定義，然後將定義匯入您的 API 中心。

匯入從 APIM 匯出之 API 定義的可能方式包括：
- 執行 [az apic api register] 以在您的 API 中心註冊新的 API。
- 執行 [az apic api definition import-specification] 以將 API 定義匯入現有的 API。
選項 2：使用 az apic import-from-apim 命令，將 API 直接從 API 管理匯入至 API 中心。

從 APIM 匯入 API 定義後，您可以在 API 中心新增中繼資料和文件，以協助專案關係人探索、了解及取用 API。

提示

您也可以設定從 API 管理到 API 中心的 API 自動同步處理。如需詳細資訊，請參閱將 API 管理實例連結至 API 中心。

必要條件

Azure 訂用帳戶中的 API 中心。如果您沒有，請參閱快速入門：建立您的 API 中心。
相同或不同訂用帳戶中的一或多個 Azure API 管理執行個體。當您直接從 APIM 匯入 API 時，APIM 執行個體和 API 中心必須位於相同的目錄中。如果您沒有，請參閱建立 Azure API 管理實例。
API 管理執行個體中，要新增至 API 中心的一或多個受控 API。
對於 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。
注意

az apic 命令需要 apic-extension Azure CLI 延伸模組。如果您尚未使用 az apic 命令，則可以在執行第一個 az apic 命令時動態安裝延伸模組，也可以手動安裝延伸模組。深入了解 Azure CLI 延伸模組。

如需中的最新變更和更新，請參閱apic-extension。某些功能可能需要預覽或特定版本的擴充功能。

注意

本文中的 Azure CLI 命令範例可在 PowerShell 或 Bash 殼層中執行。若因變數語法不同而有需要，可參考為兩個殼層提供的個別命令範例。

選項 1：從 APIM 匯出 API 定義，並將其匯入您的 API 中心

首先，使用 [az apim api export] 命令將 API 從 APIM 執行個體匯出至 API 定義。視您的案例而定，您可以將 API 定義匯出至本機檔案或 URL。

將 API 匯出至本機 API 定義檔案

下列範例命令會匯出在 myAPIManagement 執行個體中識別碼為 my-api 的 API。 API 會以 OpenApiJson 格式匯出至您指定路徑的本機 OpenAPI 定義檔案。

#! /bin/bash
az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonFile \
    --file-path "/path/to/folder"

# Formatted for PowerShell
az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonFile `
    --file-path '/path/to/folder'

將 API 匯出至 URL

在下列範例中，[az apim api export] 會以 OpenApiJson 格式將識別碼為 my-api 的 API 匯出至 Azure 儲存體中的 URL。 URL 的可用時間約為五分鐘。在這裡，URL 的值會儲存在 $link 變數中。

#! /bin/bash
link=$(az apim api export --api-id my-api --resource-group myResourceGroup \
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link \
    --output tsv)

# Formatted for PowerShell
$link=$(az apim api export --api-id my-api --resource-group myResourceGroup `
    --service-name myAPIManagement --export-format OpenApiJsonUrl --query properties.value.link `
    --output tsv)

從匯出的 API 定義在您的 API 中心註冊 API

您可以使用 [az apic api register] 命令從匯出的定義在 API 中心註冊新的 API。

下列範例會從名為 definitionFile.json 的本機 OpenAPI 定義檔案，在 myAPICenter API 中心註冊 API。

az apic api register --resource-group myResourceGroup --service-name myAPICenter --api-location "/path/to/definitionFile.json"

將 API 定義匯入至 API 中心的現有 API

下列範例會使用 [az apic api definition import-specification] 命令將 API 定義匯入 myAPICenter API 中心的現有 API。在這裡，API 定義會從儲存在 $link 變數中的 URL 匯入。

此範例會假設您有一個名為 [my-api] 的 API，相關聯的 API 版本 v1-0-0，以及 API 中心中的定義實體 openapi。如果您沒有，請參閱將 API 新增至 API 中心。

#! /bin/bash
az apic api definition import-specification \
    --resource-group myResourceGroup --service-name myAPICenter \
    --api-id my-api --version-id v1-0-0 \
    --definition-id openapi --format "link" --value '$link' \
    --specification '{"name":"openapi","version":"3.0.2"}'

# Formatted for PowerShell
az apic api definition import-specification `
    --resource-group myResourceGroup --service-name myAPICenter `
    --api-id my-api --version-id v1-0-0 `
    --definition-id openapi --format "link" --value '$link' `
    --specification '{"name":"openapi","version":"3.0.2"}'

選項 2：直接從您的 APIM 執行個體匯入 API

以下是使用 [az apic service import-from-apim] 命令將 API 從您的 APIM 執行個體匯入 API 中心的步驟。當您想要將多個 API 從 API 管理匯入至 API 中心時，此命令很有用。您也可以使用它來匯入單一 API。

當您使用 az apic import-from-apim 將 APIM 執行個體的 API 新增至 API 中心時，會自動發生下列情況：

每個 API 的版本、定義和部署資訊都會複製到您的 API 中心。
API 會在您的 API 中心接收系統產生的 API 名稱。它會保有 API 管理中的顯示名稱 (標題)。
API 的 [生命週期階段] 會設定為「設計」。
Azure API 管理會新增為環境。

在 API 中心新增受控識別

在您的 API 中心啟用受控識別

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

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

入口網站
Azure CLI

在入口網站中，瀏覽至您的 API 中心。
在 [安全性] 下的左側功能表中，選取 [受控識別]。
選取 [系統指派]，然後將狀態設定為 [開啟]。
選取 [儲存]。

使用下列 [az apic service update] 命令，在 API 中心設定系統指派的身分識別。替換 API 中心和資源群組的名稱：

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

為受控識別指派 API 管理服務讀者角色

若要允許匯入 API，請為 API 中心的受控識別指派 API 管理執行個體中的 API 管理服務讀者角色。您可以使用入口網站或 Azure CLI。

入口網站
Azure CLI

在入口網站中，瀏覽至您的 API 管理執行個體。
在左側功能表中，選取 [存取控制 (IAM)]。
選取 [+ 新增角色指派]。
在 [新增角色指派] 窗格上設定值，如下所示：
1. 在 [角色] 索引標籤上，選取 [API 管理服務讀取器]。
2. 在 [成員] 索引標籤上的 [指派存取權的對象] 中 - 選取 [受控識別]>[+ 選取成員]。
3. 在 [ 選取受控識別 ] 頁面上，選取您在上一節中新增之 API 中心的系統指派受控識別。按一下 [選取]。
4. 選取檢閱+指派。

取得身分識別的主體識別碼。針對系統指派身分識別，請使用 [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)

使用 az apim show 命令，取得 API 管理執行個體的資源識別碼。

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

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

使用 az role assignment create 命令，為受控識別指派 API 管理執行個體中的 API 管理服務讀者角色。

#! /bin/bash
scope="${apimID:1}"

az role assignment create \
    --role "API Management Service Reader Role" \
    --assignee-object-id $apicObjID \
    --assignee-principal-type ServicePrincipal \
    --scope $scope

# Formatted for PowerShell
$scope=$apimID.substring(1)

az role assignment create `
    --role "API Management Service Reader Role" `
    --assignee-object-id $apicObjID `
    --assignee-principal-type ServicePrincipal `
    --scope $scope

從 API 管理匯入 API

使用 [az apic service import-from-apim] 命令，將一或多個 API 從您的 APIM 執行個體匯入 API 中心。

注意

此命令取決於在您的 API 中心設定、對 API 管理執行個體具有讀取權限的受控識別。如果您尚未新增或設定受控識別，請參閱本文前述的在 API 中心新增受控識別。
如果您的 API 中心有多個受控識別，該命令會先搜尋系統指派的身分識別。如果找不到任何身分識別，則會挑選清單中第一個由使用者指派的身分識別。

從 API 管理執行個體匯入所有 API

在下列命令中，取代您的 API 中心、API 中心的資源群組、APIM 執行個體和執行個體的資源群組的名稱。使用 * 來指定 APIM 執行個體中的所有 API。

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis '*'

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis '*'

注意

如果您的 API 管理執行個體有大量 API，則匯入至 API 中心可能需要一些時間。

從 API 管理執行個體匯入特定 API

使用名稱指定要從 API 管理執行個體匯入的 API。

在下列命令中，取代您的 API 中心、API 中心的資源群組、APIM 執行個體和執行個體的資源群組的名稱。使用 petstore-api 參數傳遞 API 名稱，例如 --apim-apis。

#! /bin/bash
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> \
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> \
    --apim-apis 'petstore-api'

# Formatted for PowerShell
az apic import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> `
    --apim-name <api-management-name> --apim-resource-group <api-management-resource-group-name> `
    --apim-apis 'petstore-api'

注意

使用 APIM 執行個體中的 API 資源名稱來指定 API 名稱，而不是顯示名稱。例如：使用 petstore-api，而非 Petstore API。

從 API 管理匯入 API 後，您可以在 API 中心檢視及管理匯入的 API。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-10-02