匯入 OpenAPI 規格

2025-05-20

適用於：所有 API 管理層

本文說明如何使用各種工具，將「OpenAPI 規格」後端 API 匯入 Azure API 管理。本文也說明如何在 API 管理中測試 API。

在本文中，您將學會如何：

使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 匯入 OpenAPI 規格
在 Azure 入口網站中測試 API

注意

API 匯入限制記載於 API 匯入的限制和已知問題中。

必要條件

API 管理執行個體。如果您還沒有執行個體，請完成下列快速入門：建立 Azure API 管理執行個體。
Azure 命令列介面 (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。
Azure PowerShell
- 如果您選擇在本機使用 Azure PowerShell：
  - 安裝最新版的 Az PowerShell 模組。
  - 使用 Connect-AzAccount Cmdlet 連線至 Azure 帳戶。
- 如果您選擇使用 Azure Cloud Shell：
  - 請參閱 Azure Cloud Shell 概觀以取得詳細資訊。

匯入後端 API

在此範例中，您會匯入開放原始碼 Petstore API 的 OpenAPI 規格，但您可以替代您選擇的 OpenAPI 規格。

在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
在左側功能表中，選取 [API] > [+ 新增 API]。
在 [從定義建立] 底下，選取 [OpenAPI]。
輸入 API 設定。您可以在建立期間設定這些值，或稍後前往 [設定] 索引標籤來進行設定。這些設定會在匯入和發佈您的第一個 API 教學課程中說明。
選取建立。

下列範例會使用 az apim api import 命令，將 OpenAPI 規格從指定的 URL 匯入名為 apim-hello-world 的 API 管理執行個體。若要使用規格的路徑而非 URL 匯入，請使用 --specification-path 參數。

# API Management service-specific details
APIMServiceName="apim-hello-world"
ResourceGroupName="myResourceGroup"

# API-specific details
APIId="swagger-petstore"
APIPath="store"
SpecificationFormat="OpenAPI"
SpecificationURL="https://petstore3.swagger.io/api/v3/openapi.json"

# Import API
az apim api import --path $APIPath --resource-group $ResourceGroupName \
    --service-name $APIMServiceName --api-id $APIId \
    --specification-format $SpecificationFormat --specification-url $SpecificationURL

匯入 API 之後，您可以視需要使用 az apim api update 命令來更新設定。

下列範例會使用 Import-AzApiManagementApi Azure PowerShell Cmdlet，將 OpenAPI 規格從指定的 URL 匯入名為 apim-hello-world 的 API 管理執行個體。若要使用規格的路徑而非 URL 匯入，請使用 -SpecificationPath 參數。

# API Management service-specific details
$apimServiceName = "apim-hello-world"
$resourceGroupName = "myResourceGroup"

# API-specific details
$apiId = "swagger-petstore"
$apiPath = "store"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://petstore3.swagger.io/api/v3/openapi.json"

# Get context of the API Management instance. 
$context = New-AzApiManagementContext -ResourceGroupName $resourceGroupName -ServiceName $apimServiceName

# Import API
Import-AzApiManagementApi -Context $context -ApiId $apiId -SpecificationFormat $specificationFormat -SpecificationUrl $specificationUrl -Path $apiPath

匯入 API 之後，您可以視需要使用 Set-AzApiManagementApi Cmdlet 來更新設定。

檢視和編輯 OpenAPI 規格

在入口網站中，使用 OpenAPI 規格編輯器來檢視、驗證或編輯您匯入之 API 的規格。

若要使用 OpenAPI 規格編輯器：

在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。
在左側功能表中的 [API] 底下，選取 ]。
在 [設計] 索引標籤的 [前端] 中，選取 [OpenAPI 規格編輯器] （鉛筆圖示）。您可以使用 JSON 或 YAML 格式開啟規格。
視需要檢閱或編輯規格。儲存您的變更。

根據 OpenAPI 規格架構進行驗證

您可以設定 APIM 驗證原則，以針對 OpenAPI 規格中的架構驗證要求和回應 (或元素)。例如，使用 validate-content 原則來驗證要求或回應本文的大小或內容。

在入口網站中測試新的 API

您可以從入口網站直接呼叫作業，以方便管理員檢視和測試 API 的作業。

選取您在上一個步驟中建立的 API。
選取 [測試] 索引標籤。
選取作業。頁面會顯示查詢參數的欄位和標頭的欄位。

注意

在測試主控台中，API 管理會自動填入 Ocp-Apim-Subscription-Key 標頭，並設定內建所有存取訂用帳戶的訂用帳戶金鑰。此金鑰可讓您存取 API 管理執行個體中的每個 API。 (選擇性) 選取 [HTTP 要求] 旁的「眼睛」圖示以顯示 Ocp-Apim-Subscription-Key 標頭。
視作業而定，輸入查詢參數值、標頭值或要求本文。請選取傳送。

測試成功時，後端會以成功的 HTTP 回應碼和某些資料進行回應。

提示

根據預設，測試主控台會將要求傳送至 APIM 的 CORS Proxy，此 Proxy 會將要求轉送至 APIM 執行個體，然後 APIM 執行個體又將其轉送至後端。此 Proxy 使用公用 IP 位址 13.91.254.72，而且只能連線到公用端點。如果您想要直接從瀏覽器將要求傳送至 APIM 服務，請選取 [略過 CORS Proxy]。當您想要使用測試主控台，且 APIM 閘道與網路隔離或不允許來自 CORS Proxy 的流量時，請使用此選項。