Esercitazione: Importare e pubblicare la prima API

SI APPLICA A: Tutti i livelli di API Management

Questa esercitazione illustra come importare un'API back-end della specifica OpenAPI in formato JSON in Azure API Management. Per questo esempio, si importa l'API open source Petstore.

Quando si importa l'API back-end in API Management, l'API di API Management diventa il gateway per l'API back-end. È possibile personalizzare il gateway in base alle proprie esigenze in API Management senza modificare l'API back-end. Per altre informazioni, vedere Trasformare e proteggere l'API.

In questa esercitazione verranno illustrate le procedure per:

Dopo l'importazione, è possibile gestire l'API nel Azure portal.

Prerequisiti

• Comprendere Azure API Management terminologia.
• Creare un'istanza Azure API Management.

Vai alla tua istanza di API Management

1. Nella Azure portale cercare e selezionare API Management services:

   

2. Nella pagina API Management services selezionare l'istanza di API Management:

   

Importare e pubblicare un'API back-end

Questa sezione illustra come importare e pubblicare un'API back-end Specifica OpenAPI.

1. Nell'istanza di API Management, in APIs nel menu della barra laterale selezionare APIs.

2. Selezionare il riquadro OpenAPI.

3. Nella finestra Crea dalla specifica OpenAPI selezionare Completa.

4. Immettere i valori dalla tabella seguente.

   È possibile impostare i valori dell'API durante la creazione o successivamente dalla scheda Impostazioni.

   

   Impostazione	valore	Descrizione
   Specifica OpenAPI	https://petstore3.swagger.io/api/v3/openapi.json -o- https://petstore.swagger.io/v2/swagger.json	Specifica il servizio back-end che implementa l'API e le operazioni supportate dall'API. L'URL del servizio back-end viene visualizzato più avanti come URL del servizio Web nella pagina Impostazioni dell'API. Dopo l'importazione, è possibile aggiungere, modificare, rinominare o eliminare operazioni della specifica.
   Includere i parametri di query nei modelli di operazione	Selezionata (impostazione predefinita)	Specifica se importare i parametri di query necessari nella specifica come parametri del modello in API Management.
   Nome visualizzato.	Dopo aver immesso l'URL della specifica OpenAPI, API Management compila questo campo in base al codice JSON.	Nome visualizzato nel portale per sviluppatori.
   Nome	Dopo aver immesso l'URL della specifica OpenAPI, API Management compila questo campo in base al codice JSON.	Nome univoco per l'API.
   Descrizione	Dopo aver immesso l'URL della specifica OpenAPI, API Management compila questo campo in base al codice JSON.	Descrizione facoltativa per l'API.
   Schema URL	HTTPS	Quali protocolli possono access'API.
   Suffisso URL dell'API	petstore	Il suffisso aggiunto all'URL di base per il servizio API Management. API Management distingue e instrada le API in base al suffisso, quindi il suffisso deve essere univoco per ogni API per un determinato publisher. Altre informazioni su come API Management instradano le richieste.
   Tag		Tag per l'organizzazione delle API per la ricerca, il raggruppamento o il filtro.
   Prodotti	Senza limitazioni	Associazione di una o più API. In alcuni livelli, l'istanza di API Management include due prodotti di esempio: Starter e Unlimited. Si pubblica un'API nel portale per sviluppatori associandola a un prodotto. È possibile includere numerose API in un prodotto e offrire le sottoscrizioni del prodotto agli sviluppatori tramite il portale per sviluppatori. Per aggiungere questa API a un altro prodotto, digitare o selezionare il nome del prodotto. Ripetere questo passaggio per aggiungere l'API a più prodotti. È anche possibile aggiungere API ai prodotti in un secondo momento dalla pagina Impostazioni. Per altre informazioni sui prodotti, vedere Creare e pubblicare un prodotto.
   Gateway	Gestito	Gateway API che espongono l'API. Questo campo è disponibile solo nei servizi di livello Developer e Premium. Managed indica il gateway integrato nel servizio API Management e ospitato da Microsoft in Azure. I gateway self-hosted sono disponibili solo nei livelli di servizio Premium e Developer. possono essere distribuiti in locale o in altri cloud. Se non si selezionano gateway, l'API non è disponibile e le richieste API non hanno esito positivo.
   Assegnare un numero di versione all'API?	Selezionare o deselezionare	Per altre informazioni, vedere Pubblicare più versioni dell'API.

5. Selezionare Crea per creare l'API.

Se si verificano problemi durante l'importazione di una definizione API, vedere Restrizioni di importazione api e problemi noti.

Visualizzare e modificare le impostazioni dell'API

Dopo aver importato l'API, è possibile visualizzare e modificare le impostazioni e le operazioni nella Azure portal.

1. Nell'istanza di API Management, in APIs nel menu della barra laterale selezionare APIs.

2. Selezionare l'API importata, ad esempio Swagger Petstore.

3. Selezionare la scheda Progettazione per visualizzare e modificare le operazioni API nella specifica OpenAPI, tra cui:

   • Dettagli dell'operazione, ad esempio URL, metodo e descrizione
   • Definizioni di richiesta e risposta
   • Criteri per modificare richieste e risposte

4. Selezionare la scheda Impostazioni per visualizzare e modificare i dettagli di configurazione dell'API, tra cui:

   • Nome visualizzato, nome e descrizione
   • URL del servizio Web (servizio back-end), schema URL e suffisso URL API
   • Prodotti, tag e controllo delle versioni
   • Impostazioni più avanzate, ad esempio i requisiti di sottoscrizione, la sicurezza e il monitoraggio

Mentre segui i tutorial di API Management, apprendi di più sulla configurazione delle impostazioni API. È possibile aggiornare queste impostazioni in qualsiasi momento per personalizzare la configurazione dell'API.

Testare la nuova API nel Azure portal

È possibile chiamare le operazioni API direttamente dal Azure portal, che offre un modo pratico per visualizzare e testare le operazioni. Nella console di test del portale, per impostazione predefinita, le API vengono chiamate utilizzando una chiave API dalla sottoscrizione integrata con accesso completo. È inoltre possibile testare le chiamate API usando una chiave della sottoscrizione associata a un prodotto.

1. Nell'istanza di API Management selezionare APIs>APIs>Swagger Petstore.

2. Selezionare la scheda Test, quindi selezionare Trova animali domestici per stato. La pagina mostra il parametro di query stato. Selezionare uno dei valori disponibili, ad esempio In sospeso. È anche possibile aggiungere qui parametri di query e intestazioni.

   Nella sezione richiesta HTTP l'intestazione Ocp-Apim-Subscription-Key viene compilata automaticamente ed è possibile visualizzarla se si seleziona l'icona a forma di occhio.

3. Selezionare Send (Invia).

   

   Il back-end risponde con 200 OK e alcuni dati.

Come API Management instrada le richieste

API Management funge da gateway tra i client API e i servizi back-end. Quando un client effettua una richiesta a un'API gestita da API Management, il routing segue questo modello:

Richiesta URL del client:
[API Management gateway URL] + [API URL suffix] + [Operation endpoint]

API Management inoltra la richiesta al servizio back-end usando questo modello:

URL del servizio back-end:
[Web service URL] + [Operation endpoint]

La tabella seguente descrive ogni parametro di routing nel contesto dell'esempio di API Petstore usato in questa esercitazione:

Esempio: Ricerca di animali domestici per stato

Uso dell'API Petstore importata in questa esercitazione:

• Il client chiama la gestione delle API:
  https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

  • URL del gateway API Management: https://apim-hello-world.azure-api.net
  • Suffisso URL API: petstore
  • Endpoint dell'operazione: /pet/findByStatus

• API Management instrada ai backend:
  https://petstore3.swagger.io/api/v3/pet/findByStatus?status=pending

  • URL servizio Web: https://petstore3.swagger.io/api/v3
  • Endpoint dell'operazione: /pet/findByStatus (come nella definizione di gestione API)

Passo successivo

Passare all'esercitazione successiva per imparare a creare e pubblicare un prodotto: