從 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 中心,請參閱 快速入門:建立 API 中心。
相同或不同訂用帳戶中的一或多個 Azure API 管理 實例。 當您直接從 API 管理 匯入 API 時,API 管理 實例和 API 中心必須位於相同的目錄中。 如果您尚未建立 Azure 實例,請參閱建立 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 管理 保留其顯示名稱(title)。
- API 的生命週期階段會設定為 [設計]。
- Azure API 管理 會新增為環境。
在 API 中心新增受控識別
在此案例中,您的 API 中心會使用受控識別來存取 API 管理 實例中的 API。 根據您的需求,設定系統指派或一或多個使用者指派的受控識別。
下列範例示範如何使用 Azure 入口網站 或 Azure CLI 來設定系統指派的受控識別。 概括而言,設定步驟與使用者指派的受控識別類似。
將受控識別指派給 API 管理 服務讀取者角色
若要允許匯入 API,請將 API 管理 實例中的 API 管理 服務讀取者角色指派給 API 中心受控識別。 您可以使用入口 網站或 Azure CLI。
- 在入口網站中,瀏覽至您的 API 管理執行個體。
- 在左側功能表中,選取 [存取控制 (IAM)]。
- 選取 [+ 新增角色指派]。
- 在 [ 新增角色指派 ] 頁面上,設定值,如下所示:
- 在 [角色] 索引標籤上 - 選取 [API 管理 服務讀取器]。
- 在 [成員] 索引標籤的 [指派存取權- 選取受控識別>+ 選取成員]。
- 在 [ 選取受控識別 ] 頁面上 - 選取您在上一節中新增之 API 中心的系統指派受控識別。 按一下 [選取]。
- 選取檢閱+指派。
從 API 管理 匯入 API
使用 az apic service import-from-apim 命令,將一或多個 API 從 API 管理 實例匯入至 API 中心。
注意
此命令取決於您 API 中心所設定的受控識別,該受控識別具有 API 管理 實例的讀取許可權。 如果您尚未新增或設定受控識別,請參閱 本文稍早在 API 中心 新增受控識別。
如果您的 API 中心有多個受控識別,命令會先搜尋系統指派的身分識別。 如果找不到任何身分識別,它會挑選清單中第一個使用者指派的身分識別。
從 API 管理 實例匯入所有 API
使用通配符 (*
) 指定來自 API 管理 實體的所有 API。
使用 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)
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。
使用 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)
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-name>
在 API 管理 實例中使用 API 資源名稱,而不是顯示名稱。 範例:petstore-api
而不是Petstore API
。
從 API 管理 匯入 API 之後,您可以在 API 中心檢視和管理匯入的 API。