Condividi tramite

Esercitazione: Importare e pubblicare la prima API

SI APPLICA A: Tutti i livelli di Gestione API

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

Suggerimento

I team API possono usare questa funzionalità nelle aree di lavoro. Le aree di lavoro forniscono accesso amministrativo isolato alle API e ai propri ambienti di runtime API.

Quando si importa l'API back-end in Gestione API, l'API di Gestione API diventa una facciata per l'API back-end. È possibile personalizzare la facciata in base alle esigenze in Gestione API senza modificare l'API back-end. Per altre informazioni, vedere Trasformare e proteggere l'API.

In questa esercitazione apprenderai a:

  • Importare un'API in Gestione API
  • Visualizzare e modificare le impostazioni dell'API
  • Testare l'API nel portale di Azure
  • Instradare le richieste API tramite Gestione API

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

Screenshot di una nuova API in Gestione API nel portale.

Prerequisiti

Passare all'istanza di Gestione API

  1. Nel portale di Azure cercare e selezionare Servizi gestione API:

    Screenshot che mostra i servizi gestione API nei risultati della ricerca.

  2. Nella pagina Servizi Gestione API selezionare l'istanza di Gestione API:

    Screenshot che mostra un'istanza di Gestione API nella pagina Servizi Gestione API.

Importare e pubblicare un'API back-end

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

  1. Nel pannello di navigazione a sinistra dell'istanza di Gestione API, in API, selezionare API.

  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.

    Screenshot della creazione di un'API nel portale.

    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 Gestione API.
    Nome visualizzato Dopo aver immesso l'URL della specifica OpenAPI, Gestione API compila questo campo in base al codice JSON. Nome visualizzato nel portale per sviluppatori.
    Nome Dopo aver immesso l'URL della specifica OpenAPI, Gestione API compila questo campo in base al codice JSON. Nome univoco per l'API.
    Descrizione Dopo aver immesso l'URL della specifica OpenAPI, Gestione API compila questo campo in base al codice JSON. Descrizione facoltativa per l'API.
    Schema URL HTTPS Protocolli che possono accedere all'API.
    Suffisso dell'URL dell'API petstore Suffisso aggiunto all'URL di base per il servizio Gestione API. Gestione API distingue e instrada le API in base al suffisso, quindi il suffisso deve essere univoco per ogni API per un determinato editore. Altre informazioni su come Gestione API instrada le richieste.
    Tag Tag per l'organizzazione delle API per la ricerca, il raggruppamento o il filtro.
    Prodotti Illimitato Associazione di una o più API. In alcuni livelli, Gestione API'istanza include due prodotti di esempio: Starter e Unlimited. Si pubblica un'API nel portale per sviluppatori associando l'API a un prodotto.

    È possibile includere numerose API in un prodotto e offrirle sottoscrizioni al 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.

    Gestito indica il gateway integrato nel servizio Gestione API e ospitato da Microsoft in Azure. I gateway self-hosted sono disponibili solo nei livelli di servizio Premium e Developer e 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 a questa API? Selezionare o deselezionare Per altre informazioni, vedere Pubblicare più versioni dell'API.

  5. Selezionare Crea per creare l'API.

In caso di problemi durante l'importazione della definizione API, vedere l'elenco delle restrizioni e dei problemi noti.

Visualizzare e modificare le impostazioni dell'API

Dopo aver importato l'API, è possibile visualizzare e modificare le impostazioni e le operazioni nel portale di Azure.

  1. Nel pannello di navigazione a sinistra dell'istanza di Gestione API, in API, selezionare API.

  2. Selezionare l'API importata, ad esempio Swagger Petstore. Screenshot delle impostazioni API in Gestione API nel portale.

  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

Durante le esercitazioni su Gestione API, sono disponibili altre informazioni sulla configurazione delle impostazioni dell'API. È possibile aggiornare queste impostazioni in qualsiasi momento per personalizzare la configurazione dell'API.

Testare la nuova API nel portale di Azure

È possibile chiamare le operazioni API direttamente dal portale di Azure, che rappresenta una soluzione pratica per visualizzare e testare le operazioni. Nella console di test del portale, per impostazione predefinita le API vengono chiamate usando una chiave della sottoscrizione a tutti gli accessi integrata. È inoltre possibile testare le chiamate API usando una chiave della sottoscrizione associata a un prodotto.

  1. Nel riquadro di navigazione a sinistra dell'istanza di Gestione API selezionare API>API>Swagger Petstore.

  2. Selezionare la scheda Test e quindi selezionare Trova animali domestici per stato. La pagina mostra il parametro Query di 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 con l’occhio.

  3. Selezionare Invia.

    Screenshot del test di un'API in portale di Azure.

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

Come la gestione delle API instrada le richieste

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

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

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

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

Annotazioni

L'endpoint operazione deve essere identico sia nella definizione dell'API Gestione API che nel servizio back-end per il corretto funzionamento del routing. Gli endpoint dell'operazione non corrispondenti generano errori di routing 404 o altri.

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

Parametro Descrizione Esempio (API Petstore)
URL del gateway di Gestione API URL di base dell'istanza di Gestione API https://apim-hello-world.azure-api.net
Suffisso dell'URL dell'API Suffisso univoco che identifica l'API in Gestione API (configurata durante la creazione dell'API) petstore
URL del servizio Web URL di base del servizio back-end derivato dalla specifica OpenAPI https://petstore3.swagger.io/api/v3
Endpoint dell'operazione Percorso di un endpoint dell'operazione specifico (derivato dalla tua specifica API) /pet/findByStatus

Esempio: Ricerca di animali domestici per stato

Uso dell'API Petstore importata in questa esercitazione:

  1. Client chiama API Management:
    https://apim-hello-world.azure-api.net/petstore/pet/findByStatus?status=pending

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

  2. Gestione API indirizza al back-end:
    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)

Passaggi successivi

Questa esercitazione ha descritto come:

  • Importare la prima API
  • Visualizzare e modificare le impostazioni dell'API
  • Testare l'API nel portale di Azure
  • Instradare le richieste API tramite Gestione API

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

Creare e pubblicare un prodotto

  • Last updated on