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

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

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

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

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

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

• 選項 2 - 使用 az apic service import-from-apim 命令，直接從 API 管理 匯入 API 中心。

從 API 管理 匯入 API 定義或 API 之後，您可以在 API 中心新增元數據和檔，以協助項目關係人探索、瞭解及取用 API。

必要條件

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

• Azure API 管理 的一或多個實例，位於相同或不同的訂用帳戶中。 當您直接從 API 管理 匯入 API 時，API 管理 實例和 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 延伸模組。

  注意

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

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

首先，使用 az apim api export 命令，將 API 從 API 管理 實例匯出至 API 定義。 視您的案例而定，您可以將 API 定義匯出至本機檔案或 URL。

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

下列範例命令會在 API 的 myAPIManagement 實例中匯出標識碼為 my-api 的 API。 API 會以 OpenApiJson 格式匯出至名為 specificationFile.json 的本機 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"

#! PowerShell syntax
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 格式的 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)

# PowerShell syntax
$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 myAPICenter --api-location "/path/to/definitionFile.json"

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

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

此範例假設您在 API 中心有名為 my-api 的 API 和相關聯的 API 版本 v1-0-0 和定義實體 openapi 。 如果您未這麼做，請參閱 將 API 新增至 API 中心。

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

# PowerShell syntax
az apic api definition import-specification `
    --resource-group myResourceGroup --service 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：直接從 API 管理 實例匯入 API

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

當您使用 az apic service import-from-apim將 API 從 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 service 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 service show 命令。

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

   # PowerShell syntax
   $apicObjID=$(az apic service 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)
   

   # PowerShell syntax
   $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 
   

   #! PowerShell syntax
   $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 從您的 API 管理執行個體匯入至 API 中心。

注意

• 此命令取決於在您的 API 中心設定、對 API 管理執行個體具有讀取權限的受控識別。 如果您尚未新增或設定受控識別，請參閱本文前述的在 API 中心新增受控識別。

• 如果您的 API 中心有多個受控識別，該命令會先搜尋系統指派的身分識別。 如果找不到任何身分識別，則會挑選清單中第一個由使用者指派的身分識別。

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

使用萬用字元 (*) 可指定 API 管理執行個體中的所有 API。

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

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

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

2. 使用 az apic service import-from-apim 命令匯入 API。 請替換 API 中心和資源群組的名稱，並使用 * 指定 API 管理執行個體中的所有 API。

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/*  
   

   注意

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

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

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

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

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

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

2. 使用 az apic service import-from-apim 命令匯入 API。 請替換 API 中心和資源群組的名稱，並指定 API 管理執行個體中的 API 名稱。

   az apic service import-from-apim --service-name <api-center-name> --resource-group <resource-group-name> --source-resource-ids $apimID/apis/<api-name>    
   

   注意

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

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

相關內容

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