從 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] 命令從 APIM 執行個體匯出 API 定義。 然後，將定義匯入您的 API 中心。

  匯入從 APIM 匯出之 API 定義的可能方式包括：

  • 執行 [az apic api register] 以在您的 API 中心註冊新的 API。
  • 執行 [az apic api definition import-specification] 以將 API 定義匯入現有的 API。

• 選項 2 - 使用 [az apic import-from-apim] 命令直接從 APIM 將 API 匯入 API 中心。

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

提示

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

必要條件

• Azure 訂用帳戶中的 API 中心。 如果您尚未建立，請參閱快速入門：建立您的 API 中心。

• Azure APIM 的一或多個執行個體，位於相同或不同的訂用帳戶中。 當您直接從 APIM 匯入 API 時，APIM 執行個體和 API 中心必須位於相同的目錄中。 如果您尚未建立，請參閱建立 Azure API 管理執行個體。

• API 管理執行個體中，要新增至 API 中心的一或多個受控 API。

• 對於 Azure CLI：

  • 在 Azure Cloud Shell 中使用 Bash 環境。 如需詳細資訊，請參閱 Azure Cloud Shell 中的 Bash 快速入門。

    

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

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

    • 出現提示時，請在第一次使用時安裝 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 大約可使用 5 分鐘。 在這裡，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 從 APIM 匯入 API 中心時，此命令很有用，但您也可以使用它來匯入單一 API。

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

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

在 API 中心新增受控識別

在此案例中，API 中心使用受控識別來存取 API 管理執行個體中的 API。 根據您的需求，設定系統指派或一或多個使用者指派的受控識別。

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

入口網站

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

Azure CLI

使用下列 [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。

入口網站

1. 在入口網站中，瀏覽至您的 API 管理執行個體。
2. 在左側功能表中，選取 [存取控制 (IAM)]。
3. 選取 [+ 新增角色指派]。
4. 在 [新增角色指派] 窗格上設定值，如下所示：
   1. 在 [角色] 索引標籤上 - 選取 [API 管理服務讀者]。
   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 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)
   

3. 使用 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 執行個體和執行個體的資源群組的名稱。 使用 --apim-apis 參數傳遞 API 名稱，例如 petstore-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 '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。

相關內容

• API 中心的 Azure CLI 參考
• APIM 的 Azure CLI 參考
• 使用 Azure CLI 命令管理 API 詳細目錄
• 將 Azure 角色指派給受控識別
• Azure API 管理文件