匯入 OpenAPI 規格

適用於：所有 API 管理層

此文章示範如何匯入位於 https://conferenceapi.azurewebsites.net?format=json 的「OpenAPI 規格」後端 API。 這個後端 API 是由 Microsoft 所提供且裝載於 Azure 上。 本文也會示範如何測試 APIM API。

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

• 使用 Azure 入口網站、Azure CLI 或 Azure PowerShell 匯入 OpenAPI 規格
• 在 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

入口網站

1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。

2. 在左側功能表中，選取 [API] > [+ 新增 API]。

3. 在 [從定義建立] 底下，選取 [OpenAPI]。

   

4. 輸入 API 設定。 您可以在建立期間設定這些值，或稍後前往 [設定] 索引標籤來進行設定。這些設定會在 匯入和發佈您的第一個 API 教學課程中說明。

5. 選取 建立。

Azure CLI

下列範例會使用 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="demo-conference-api"
APIPath="conference"
SpecificationFormat="OpenAPI"
SpecificationURL="https://conferenceapi.azurewebsites.net/?format=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 命令來更新設定。

PowerShell

下列範例會使用 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 = "demo-conference-api"
$apiPath = "conference"
$specificationFormat = "OpenAPI"
$specificationUrl = "https://conferenceapi.azurewebsites.net/?format=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 來更新設定。

在入口網站中測試新的 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。

注意

在您匯入另一個 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

根據 OpenAPI 規格進行驗證

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

下一步

• 建立和發佈產品
• 轉換及保護已發佈的 API