匯入 OpenAPI 規格

適用於：所有 API 管理層

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

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

必要條件

• API 管理執行個體。 如果您還沒有執行個體，請完成下列快速入門：建立 Azure 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。

• Azure PowerShell

  • 如果您選擇在本機使用 Azure PowerShell：
    • 安裝最新版的 Az PowerShell 模組。
    • 使用 Connect-AzAccount Cmdlet 連線至 Azure 帳戶。
  • 如果您選擇使用 Azure Cloud Shell：
    • 請參閱 Azure Cloud Shell 概觀 以取得詳細資訊。

匯入後端 API

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

# 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 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

檢視和編輯 OpenAPI 規格

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

若要使用 OpenAPI 規格編輯器：

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

根據 OpenAPI 規格架構進行驗證

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

在入口網站中測試新的 API

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

1. 選取您在上一個步驟中建立的 API。

2. 選取 [測試] 索引標籤。

3. 選取作業。 頁面會顯示查詢參數的欄位和標頭的欄位。

   注意

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

4. 視作業而定，輸入查詢參數值、標頭值或要求本文。 請選取傳送。

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

   提示

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

若要偵錯 API，請參閱教學課程：使用要求追蹤對 API 進行偵錯。

附加其他 API

您可撰寫由不同服務所公開 API 的 API，包含：

• OpenAPI 規格
• SOAP API
• GraphQL API
• 在 Azure App Service 中託管的 Web 應用程式
• Azure 函數應用程式
• Azure Logic 應用程式
• Azure Service Fabric

使用下列步驟，將不同的 API 附加至您現有的 API。

1. 移至 Azure 入口網站中的 Azure API 管理執行個體。

   

2. 在 [概觀] 頁面上，或從左側功能表，選取 [API]。

   

3. 在您要附加另一個 API 的 API 旁，按一下 ...。

4. 從下拉式功能表中選取 [匯入]。

   

5. 選取要從中匯入 API 的服務。

   

相關主題

• API 匯入限制
• 匯入 OpenAPI 規格
• 匯入 SOAP API
• 匯入 SOAP API 並轉換為 REST
• 匯入 App Service API
• 匯入容器應用程式 API
• 匯入 WebSocket API
• 匯入 GraphQL API
• 匯入 GraphQL 結構描述並設定欄位解析器
• 匯入 Azure 函式應用程式
• 匯入 Azure 邏輯應用程式
• 匯入 Service Fabric 服務
• 匯入 Azure OpenAI API
• 匯入 OData API
• 匯入 SAP OData 中繼資料
• 匯入 gRPC API
• 編輯 API

下一步