Gestire la prima API in Gestione API di Azure

Panoramica

Questa guida illustra le procedure per iniziare subito a usare Gestione API di Azure ed effettuare la prima chiamata API.

Cos'è Gestione API di Azure?

È possibile usare Gestione API di Azure per avviare un programma API completo basato su qualsiasi back-end.

Gli scenari comuni includono:

  • protezione dell'infrastruttura mobile con la delega dell'accesso con le chiavi API, la prevenzione degli attacchi DOS con la limitazione oppure l'uso di criteri di sicurezza avanzata come la convalida dei token JWT.
  • abilitazione degli ecosistemi del partner ISV , offrendo al partner un rapido caricamento attraverso il portale degli sviluppatori e compilando un'interfaccia API per la separazione dalle implementazioni interne non pronte per l'utilizzo da parte del partner.
  • esecuzione di un programma API interno , offrendo all'organizzazione una posizione centralizzata per la comunicazione della disponibilità e delle ultime modifiche apportate alle API e delegando l'accesso in base agli account aziendali, tutti basati su un canale protetto tra il gateway dell'API e il back-end.

Il sistema è costituito dai componenti seguenti:

  • Il gateway dell'API è l'endpoint che:

    • Accetta chiamate API e le indirizza al back-end.
    • Verifica le chiavi API, i token JWT, i certificati e altre credenziali.
    • Applica le quote di utilizzo e i limiti di frequenza.
    • Trasforma le API in modo immediato senza modifiche del codice.
    • Memorizza nella cache le risposte di back-end durante l'installazione.
    • Registra i metadati della chiamata a scopi di analisi.
  • Il portale di pubblicazione è l'interfaccia amministrativa in cui si configura il programma API. Può essere usato per:

    • Definire o importare lo schema API.
    • Creare pacchetti di API nei prodotti.
    • Configurare criteri come quote o trasformazioni sulle API.
    • Ottenere informazioni dall'analisi.
    • Gestire gli utenti.
  • Il portale per sviluppatori funge da principale presenza Web per gli sviluppatori, che potranno:

    • Leggere la documentazione relativa alle API.
    • Provare un'API con la console interattiva.
    • Creare un account ed eseguire la sottoscrizione per ottenere le chiavi API.
    • Accedere all'analisi di utilizzo personalizzata.

Creare un'istanza di Gestione API

Nota

Per completare l'esercitazione, è necessario un account Azure. Se non si ha un account, è possibile creare un account gratuito in pochi minuti. Per informazioni dettagliate, vedere la pagina relativa alla versione di valutazione gratuita di Azure.

Per poter usare Gestione API, occorre innanzitutto creare un'istanza del servizio. Accedere al portale di Azure e fare clic su Nuovo, Web e dispositivi mobili, Gestione API.

API Management new instance

In URLspecificare un nome univoco di sottodominio da usare come URL del servizio.

Scegliere i valori di Sottoscrizione, Gruppo di risorse e Area per l'istanza del servizio.

Immettere Contoso Ltd. in Nome organizzazione e specificare l'indirizzo di posta elettronica nel campo Indirizzo di posta elettronica dell'amministratore.

Nota

Questo indirizzo di posta elettronica viene usato per le notifiche inviate dal sistema Gestione API. Per altre informazioni, vedere Come configurare notifiche e modelli di posta elettronica in Gestione API di Azure.

New API Management service

Le istanze del servizio Gestione API sono disponibili in tre livelli: Developer, Standard e Premium.

Nota

Il livello Developer è dedicato allo sviluppo, al test e alla distribuzione pilota di programmi API in cui l'elevata disponibilità non è un fattore rilevante. Nei livelli Standard e Premium è possibile aumentare il numero di unità riservate per gestire un maggior volume di traffico. I livelli Standard e Premium forniscono al servizio Gestione API anche una potenza di elaborazione e prestazioni maggiori. È possibile completare questa esercitazione usando qualsiasi livello. Per altre informazioni sui livelli di Gestione API, vedere Gestione API - Prezzi.

Fare clic su Crea per avviare il provisioning di un'istanza del servizio.

New API Management service

Dopo aver creato l'istanza del servizio, l'operazione successiva consiste nel creare o importare un'API.

Importare un'API

Un'API rappresenta un set di operazioni che possono essere richiamate da un'applicazione client. Le operazioni API vengono trasmesse tramite proxy ai servizi Web esistenti.

È possibile creare le API (e aggiungere operazioni) in modo manuale oppure è possibile importarle. In questa esercitazione, verrà importata l'API per un servizio Web calcolatrice di esempio fornito da Microsoft e ospitato in Azure.

Nota

Per indicazioni sulla creazione di un'API e l'aggiunta manuale di operazioni, vedere Come creare API in Gestione API di Azure e Come aggiungere operazioni a un'API in Gestione API di Azure.

Le API vengono configurate dal portale di pubblicazione. Per accedervi, fare clic su Publisher portal (Portale di pubblicazione) nella barra degli strumenti del servizio.

Portale di pubblicazione

Per importare l'API Calculator, fare clic su API nel menu Gestione API sulla sinistra e quindi scegliere Importa API.

Pulsante Importa API

Per configurare l'API Calcolatrice, seguire questa procedura:

  1. Fare clic su Importa dall'URL, immettere http://calcapi.cloudapp.net/calcapi.json nella casella di testo Specification document URL (URL documento specifica) e fare clic sul pulsante di opzione Swagger.
  2. Digitare calc nella casella di testo Web API URL suffix (Suffisso dell'URL dell'API Web).
  3. Fare clic sulla casella Products (optional) (Prodotti - facoltativo) e scegliere Starter.
  4. Fare clic su Salva per importare l'API.

Add new API

Nota

Gestione API supporta attualmente sia la versione 1.2 che la versione 2.0 del documento Swagger per l'importazione. Anche se la specifica Swagger 2.0 dichiara che le proprietà host, basePath e schemes sono facoltative, il documento Swagger 2.0 DEVE contenere queste proprietà. In caso contrario, non verrà importato.

Una volta importata l'API, la pagina di riepilogo dell'API viene visualizzata nel portale di pubblicazione.

Riepilogo dell'API

La sezione API comprende diverse schede. Nella scheda Riepilogo sono visualizzate le informazioni e le metriche di base sull'API. È possibile usare la scheda Impostazioni per visualizzare e modificare la configurazione di un'API. La scheda Operazioni consente di gestire le operazioni dell'API. La scheda Sicurezza consente di configurare l'autenticazione del gateway per il server back-end usando l'autenticazione di base o l'autenticazione reciproca dei certificati e di configurare l'autorizzazione utente con OAuth 2.0. La scheda Problemi consente di visualizzare i problemi segnalati dagli sviluppatori che stanno usando le API. La scheda Prodotti viene usata per configurare i prodotti contenenti l'API.

Per impostazione predefinita, con ogni istanza di Gestione API vengono forniti due prodotti di esempio:

  • Starter
  • Illimitato

In questa esercitazione, è stata aggiunta l'API Calcolatrice di base al prodotto Starter quando l'API è stata importata.

Per effettuare chiamate a un'API, gli sviluppatori devono prima sottoscrivere un prodotto che offre l'accesso all'API. La sottoscrizione dei prodotti può essere effettuata direttamente dagli sviluppatori nel portale per sviluppatori; in alternativa, gli amministratori possono sottoscrivere i prodotti per conto degli sviluppatori nel portale di pubblicazione. Dal momento che nei passaggi precedenti di questa esercitazione è stata creata un'istanza di Gestione API, l'utente corrente ha già effettuato la sottoscrizione a ogni prodotto per impostazione predefinita.

Chiamare un'operazione dal portale per sviluppatori

È possibile chiamare le operazioni direttamente dal portale per sviluppatori, che consente di visualizzare e testare le operazioni di un'API in modo pratico. In questo passaggio dell'esercitazione verrà chiamata l'operazione Aggiungere due integer dell'API Calcolatrice di base. Fare clic su Portale per sviluppatori nel menu in alto a destra del portale di pubblicazione.

Portale per sviluppatori

Fare clic su API nel menu in alto e quindi su Basic Calculator (Calcolatrice di base) per visualizzare le operazioni disponibili.

Portale per sviluppatori

Notare le descrizioni e i parametri di esempio che sono stati importati assieme alle API e alle operazioni, che costituiscono la documentazione destinata agli sviluppatori che useranno l'operazione. È possibile aggiungere queste descrizioni anche quando le operazioni vengono aggiunte manualmente.

Per chiamare l'operazione di aggiunta di due Integer, fare clic su Try it (Prova).

Prova

È possibile immettere alcuni valori per i parametri o mantenere quelli predefiniti e quindi fare clic su Invia.

HTTP Get

Dopo aver richiamato un'operazione, nel portale per sviluppatori vengono visualizzati lo stato della risposta, le intestazioni della risposta e l'eventuale contenuto della risposta.

Response

Visualizzare l'analisi

Per visualizzare l'analisi per la Calcolatrice di base, tornare al portale di pubblicazione selezionando Gestisci nel menu in alto a destra nel portale per sviluppatori.

Gestisci

La visualizzazione predefinita del portale di pubblicazione è il dashboard, che offre una panoramica dell'istanza di Gestione API.

dashboard

Passare il puntatore del mouse sul grafico della Calcolatrice di base per visualizzare le metriche specifiche relative all'utilizzo dell'API in un dato periodo di tempo.

Nota

Se il grafico non contiene linee, tornare al portale per sviluppatori ed effettuare alcune chiamate all'API, attendere qualche secondo e quindi tornare al dashboard.

Fare clic su Visualizza dettagli per visualizzare la pagina di riepilogo per l'API, inclusa una versione più estesa delle metriche visualizzate.

Analisi

Riepilogo

Per report e metriche dettagliate fare clic su Analisi nel menu Gestione API sulla sinistra.

Panoramica

La sezione Analisi include le quattro schede seguenti:

  • Riepilogo : fornisce metriche complessive sull'utilizzo e l'integrità, oltre a indicare API, operazioni e prodotti più usati e gli sviluppatori più attivi.
  • Utilizzo : fornisce informazioni dettagliate sulle chiamate API e sulla larghezza di banda, inclusa una rappresentazione geografica.
  • Integrità : è incentrata sui codici di stato, sulle percentuali di operazioni sulla cache completate, sui tempi di risposta, oltre che sui tempi di risposta di API e servizi.
  • Attività : fornisce report che illustrano in dettaglio l'attività specifica in base a sviluppatore, prodotto, API e operazione.

Passaggi successivi