Importare una specifica OpenAPI

SI APPLICA A: Tutti i livelli di Gestione API

Questo articolo illustra come importare un'API back-end "Specifica OpenAPI" in Azure Gestione API usando vari strumenti. Viene inoltre descritto come testare l'API in Gestione API.

In questo articolo vengono illustrate le operazioni seguenti:

• Importare una specifica OpenAPI usando il portale di Azure, l’interfaccia della riga di comando di Azure o Azure PowerShell
• Testare l'API nel portale di Azure

Nota

Le limitazioni relative all'importazione delle API sono documentate in Restrizioni di importazione API e problemi noti.

Prerequisiti

• Un'istanza di Gestione API. Se non è già disponibile, completare l’avvio rapido seguente: Creare un'istanza di Gestione API di Azure.

• Interfaccia della riga di comando di Azure

  • Usare l'ambiente Bash in Azure Cloud Shell. Per altre informazioni, vedere Introduzione ad Azure Cloud Shell.

    

  • Se si preferisce eseguire i comandi di riferimento dell'interfaccia della riga di comando in locale, installare l'interfaccia della riga di comando di Azure. Per l'esecuzione in Windows o macOS, è consigliabile eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker. Per altre informazioni, vedere Come eseguire l'interfaccia della riga di comando di Azure in un contenitore Docker.

    • Se si usa un'installazione locale, accedere all'interfaccia della riga di comando di Azure con il comando az login. Per completare il processo di autenticazione, seguire la procedura visualizzata nel terminale. Per altre opzioni di accesso, vedere Eseguire l'autenticazione ad Azure con l'interfaccia della riga di comando di Azure.

    • Quando richiesto, al primo utilizzo installare l'estensione dell'interfaccia della riga di comando di Azure. Per altre informazioni sulle estensioni, vedere Usare e gestire le estensioni con l'interfaccia della riga di comando di Azure.

    • Eseguire az version per trovare la versione e le librerie dipendenti installate. Per eseguire l'aggiornamento alla versione più recente, eseguire az upgrade.

• Azure PowerShell

  • Se si sceglie di usare Azure PowerShell in locale:
    • Installare la versione più recente del modulo Az di PowerShell.
    • Connettersi all'account Azure con il cmdlet Connect-AzAccount.
  • Se si sceglie di usare Azure Cloud Shell:
    • Vedere Panoramica di Azure Cloud Shell per altre informazioni.

Importare un'API back-end

Per questo esempio, si importa la specifica OpenAPI per l'API Petstore open source, ma è possibile sostituire una specifica OpenAPI di propria scelta.

Portale

1. Nel portale di Azure accedere all'istanza di Gestione API.

2. Nel menu a sinistra selezionare API >+ Aggiungi API.

3. In Crea da definizione selezionare OpenAPI.

   

4. Immettere le impostazioni API. È possibile impostare i valori durante la creazione o configurarli successivamente passando alla scheda Impostazioni. Le impostazioni sono illustrate nell'esercitazione Importare e pubblicare la prima API.

5. Seleziona Crea.

Interfaccia della riga di comando di Azure

L'esempio seguente usa il comando az apim api import per importare una specifica OpenAPI dall'URL specificato in un'istanza di Gestione API denominata apim-hello-world. Per eseguire l’importazione usando il percorso di una specifica anziché un URL, usare il parametro --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

Dopo aver importato l'API, se necessario, è possibile aggiornare le impostazioni usando il comando az apim api update.

PowerShell

L'esempio seguente usa il cmdlet Import-AzApiManagementApi Azure PowerShell per importare una specifica OpenAPI dall'URL specificato in un'istanza di Gestione API denominata apim-hello-world. Per eseguire l’importazione usando il percorso di una specifica anziché un URL, usare il parametro -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

Dopo aver importato l'API, se necessario, è possibile aggiornare le impostazioni usando il cmdlet Set-AzApiManagementApi.

Visualizzare e modificare la specifica OpenAPI

Nel portale usare l'editor delle specifiche OpenAPI per visualizzare, convalidare o modificare la specifica per l'API importata.

Per usare l'editor delle specifiche OpenAPI:

1. Nel portale di Azure accedere all'istanza di Gestione API.
2. Nel menu a sinistra, in
3. Nella scheda Progettazione, in Front-end, selezionare Editor specifiche OpenAPI (icona a forma di matita). È possibile aprire la specifica in formato JSON o YAML.
4. Esaminare o modificare la specifica in base alle esigenze. Selezionare Salva per salvare le modifiche.

Convalidare in base a uno schema di specifica OpenAPI

È possibile configurare i criteri di convalida di Gestione API per convalidare le richieste e le risposte (o i relativi elementi) sullo schema in una specifica OpenAPI. Ad esempio, usare i criteri validate-content per convalidare le dimensioni o il contenuto di una richiesta o del corpo della risposta.

Testare la nuova API nel portale

È possibile chiamare le operazioni direttamente dal portale, il che consente agli amministratori di visualizzare e testare facilmente le operazioni di un'API.

1. Selezionare l'API creata nel passaggio precedente.

2. Selezionare la scheda Test.

3. Selezionare un'operazione. La pagina visualizza campi per le intestazioni e campi per i parametri di query.

   Nota

   Nella console di test, Gestione API popola automaticamente un'intestazione Ocp-Apim-Subscription-Key e configura la chiave di sottoscrizione della sottoscrizione all-access integrata. Questa chiave consente l'accesso a ogni API nell'istanza di Gestione API. Facoltativamente, visualizzare l'intestazione Ocp-Apim-Subscription-Key selezionando l'icona "occhio" accanto alla richiesta HTTP.

4. A seconda dell'operazione, immettere i valori dei parametri di query, i valori di intestazione o il corpo della richiesta. Selezionare Invia.

   Quando il test ha esito positivo, il back-end risponde con un codice di risposta HTTP corretto e alcuni dati.

   Suggerimento

   Per impostazione predefinita, la console di test invia una richiesta al proxy CORS di Gestione API, che inoltra la richiesta all'istanza di Gestione API, che a sua volta la inoltra al back-end. Questo proxy usa l'indirizzo IP pubblico 13.91.254.72 e può raggiungere solo gli endpoint pubblici. Per inviare una richiesta direttamente dal browser al servizio Gestione API, selezionare Ignora proxy CORS. Questa opzione è utile quando si vuole usare la console di test e il gateway di Gestione API è isolato dalla rete o non consente il traffico dal proxy CORS.

Per eseguire il debug di un’API, vedere Esercitazione: Eseguire il debug delle API usando la traccia delle richieste.

Aggiungere altre API

È possibile comporre un'API fuori dalle API esposte da servizi diversi, tra cui:

• Una specifica OpenAPI
• Un'API SOAP
• Un'API GraphQL
• Un'app Web ospitata nel servizio app di Azure
• Funzioni di Azure
• App per la logica di azure
• Azure Service Fabric

Nota

Quando si importa un'API, le operazioni vengono aggiunte all'API corrente.

Per aggiungere un'API a un'API esistente:

1. Passare all'istanza di Gestione API di Azure nel portale di Azure:

   

2. Selezionare API nella pagina Panoramica o selezionare API>nel menu a sinistra.

   

3. Selezionare i puntini di sospensione (...) accanto all'API a cui si vuole aggiungere un'altra API.

4. Selezionare Importa dal menu a discesa:

   

5. Selezionare un servizio da cui importare un'API.

Contenuti correlati

• Limitazioni relative all'importazione di API
• Importare una specifica OpenAPI
• Importare un'API SOAP
• Importare un'API SOAP e convertirla in REST
• Importare un'API del servizio app
• Importare un'API dell'app contenitore
• Importare un'API WebSocket
• Importare un'API GraphQL
• Importare uno schema di GraphQL e configurare resolver di campo
• Importare un'API della Function App
• Importare un'API per un'app di logica
• Importare un servizio Service Fabric
• Importare un'API Foundry per intelligenza artificiale di Azure
• Importare un'API di OpenAI di Azure
• Importare un'API LLM
• Importare un'API OData
• Importare metadati OData SAP
• Importare un'API gRPC
• Modificare un'API