Esercitazione: Monitorare le API pubblicate

  • Articolo

SI APPLICA A: Tutti i livelli di Gestione API

Con Monitoraggio di Azure è possibile eseguire operazioni di visualizzazione, query, instradamento, archiviazione, e quindi adottare le misure appropriate, sulle metriche o sui log provenienti dal servizio Gestione API.

In questa esercitazione apprenderai a:

  • Visualizzare le metriche dell'API
  • Configurare una regola di avviso
  • Visualizzare i log attività
  • Abilitare e visualizzare i log delle risorse

Nota

Gestione API supporta una gamma di strumenti aggiuntivi per osservare le API, tra cui l'analisi predefinita e l'integrazione con Application Insights. Ulteriori informazioni

Prerequisiti

Visualizzare le metriche delle API

Gestione API genera le metriche ogni minuto in modo da ottenere una visibilità near real-time dello stato e dell'integrità delle API. Di seguito sono riportate le due metriche usate più di frequente. Per un elenco di tutte le metriche disponibili, vedere Metriche supportate.

  • Capacità: consente di prendere decisioni sull'aggiornamento o il downgrade dei servizi Gestione API. La metrica viene generata al minuto e riflette la capacità stimata del gateway al momento della creazione di report. La metrica è compresa tra 0 e 100 e viene calcolata in base alle risorse gateway, come utilizzo della CPU e della memoria.
  • Richieste: consente di analizzare il traffico dell'API che transitano attraverso i servizi di Gestione API. La metrica viene generata al minuto e segnala il numero di richieste di gateway con dimensioni. Filtrare le richieste in base a codici di risposta, posizione, nome host ed errori.

Importante

Le metriche seguenti sono state deprecate a partire da maggio 2019 e verranno ritirate nel mese di agosto 2023: richieste di gateway totali, richieste di gateway riuscite, richieste di gateway non autorizzate, richieste di gateway non riuscite, altre richieste di gateway. Eseguire la migrazione alla metrica Richieste che fornisce funzionalità equivalenti.

Screenshot delle metriche nella panoramica di Gestione API

Per accedere alle metriche:

  1. Nel portale di Azure accedere all'istanza di Gestione API. Nella scheda Monitoraggio della pagina Panoramica esaminare le metriche chiave per le API.

  2. Per analizzare in dettaglio le metriche, selezionare Metriche dal menu a sinistra.

    Screenshot della voce Metriche nel menu Monitoraggio nel portale.

  3. Nell'elenco a discesa selezionare le metriche a cui si è interessati. Ad esempio, Richieste.

  4. Il grafico mostra il numero totale di chiamate API. Regolare l'intervallo di tempo per concentrarsi sui periodi di interesse.

  5. È possibile filtrare il grafico usando le dimensioni della metrica Richieste . Ad esempio, selezionare Aggiungi filtro, selezionare Backend Response Code Category (Categoria codice di risposta back-end), immettere 500 come valore. Il grafico mostra il numero di richieste non riuscite nel back-end dell'API.

Configurare una regola di avviso

È possibile ricevere gli avvisi in base alle metriche e ai log attività. In Monitoraggio di Azure configurare una regola di avviso per eseguire un'azione quando viene attivata. Le azioni comuni includono:

  • Inviare una notifica tramite posta elettronica
  • Chiamare un webhook
  • Richiamare un'app per la logica di Azure

Per configurare una regola di avviso di esempio in base a una metrica della richiesta:

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

  2. Selezionare Avvisi dal menu a sinistra.

    Screenshot dell'opzione Avvisi nel menu Monitoraggio nel portale.

  3. Selezionare + Crea>regola di avviso.

  4. Nella finestra Selezionare un segnale nella scheda Condizione:

    1. Selezionare Metriche per Tipo segnale.
    2. Selezionare Richieste per Nome segnale.
    3. In Logica di avviso specificare un valore Soglia, ovvero il numero di occorrenze dopo il quale deve essere attivato l'avviso.
    4. In Dividi per dimensioni, in Nome dimensione selezionare Gateway Response Code Category (Categoria codice di risposta del gateway).
    5. In Valori di dimensione selezionare 4xx per gli errori client come le richieste non autorizzate o non valide. Se il valore della dimensione non viene visualizzato, selezionare Aggiungi valore personalizzato e immettere 4xx.
    6. In Quando valutare accettare le impostazioni predefinite o selezionare altre impostazioni per configurare la frequenza di esecuzione della regola. Selezionare Avanti.

    Screenshot della configurazione della logica di avviso nel portale.

  5. Nella scheda Azioni selezionare o creare uno o più gruppi di azioni per notificare agli utenti l'avviso ed eseguire un'azione. Ad esempio, creare un nuovo gruppo di azioni per inviare un messaggio di posta elettronica di notifica a admin@contoso.com. Per i passaggi dettagliati, vedere Creare e gestire gruppi di azioni nel portale di Azure.

    Screenshot della configurazione delle notifiche per il nuovo gruppo di azioni nel portale.

  6. Nella scheda Dettagli di Crea una regola di avviso immettere un nome e una descrizione della regola di avviso e selezionare il livello di gravità.

  7. Facoltativamente, configurare le impostazioni rimanenti. Quindi, nella scheda Rivedi e crea selezionare Crea.

  8. A questo punto, testare la regola di avviso chiamando l'API Conference senza una chiave API. Ad esempio:

    curl GET https://apim-hello-world.azure-api.net/conference/speakers HTTP/1.1

    Un avviso si attiva in base al periodo di valutazione e invierà un messaggio di posta elettronica a admin@contoso.com.

    Gli avvisi vengono visualizzati anche nella pagina Avvisi per l'istanza di Gestione API.

    Screenshot degli avvisi nel portale.

Log attività

I log attività forniscono informazioni dettagliate sulle operazioni sui servizi Gestione API. L'uso del log attività consente di acquisire informazioni dettagliate su qualsiasi operazione di scrittura (PUT, POST, DELETE) eseguita sui servizi Gestione API.

Nota

I log attività non includono le operazioni di lettura (GET) né le operazioni eseguite nel portale di Azure o usando le API di gestione originali.

È possibile accedere ai log attività del servizio Gestione API o ai log di tutte le risorse di Azure in Monitoraggio di Azure.

Screenshot del log attività nel portale.

Per visualizzare il log attività:

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

  2. Selezionare Log attività.

    Screenshot della voce Log attività nel menu Monitoraggio del portale.

  3. Selezionare l'ambito di filtro desiderato e fare clic su Applica.

Log risorse

I log delle risorse (log di Monitoraggio di Azure) forniscono informazioni dettagliate sulle operazioni e sugli errori Gestione API importanti per scopi di controllo e risoluzione dei problemi. Se abilitata tramite un'impostazione di diagnostica, i log raccolgono informazioni sulle richieste API ricevute ed elaborate dal gateway Gestione API.

Nota

Il livello Consumo non supporta la raccolta di log delle risorse.

Per configurare i log risorse:

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

  2. Selezionare Impostazioni di diagnostica.

    Screenshot della voce Impostazioni di diagnostica nel menu Monitoraggio nel portale.

  3. Fare clic su + Aggiungi impostazione di diagnostica.

  4. Selezionare i log o le metriche da raccogliere.

    Sono disponibili diverse opzioni su dove inviare i log e le metriche. Ad esempio, archiviare i log delle risorse insieme alle metriche a un account di archiviazione, trasmetterli a un hub eventi o inviarli a un'area di lavoro Log Analytics.

    Suggerimento

    Se si seleziona un'area di lavoro Log Analytics, è possibile scegliere di archiviare i dati nella tabella ApiManagementGatewayLogs specifica della risorsa o archiviarli nella tabella Generale di AzureDiagnostics. È consigliabile usare la tabella specifica della risorsa per le destinazioni di log che la supportano. Ulteriori informazioni

  5. Dopo aver configurato i dettagli per la destinazione o le destinazioni del log, selezionare Salva.

Nota

L'aggiunta di un oggetto impostazione di diagnostica potrebbe causare un errore se la proprietà MinApiVersion del servizio Gestione API è impostata su qualsiasi versione dell'API successiva alla versione 2022-09-01-preview.

Per altre informazioni, vedere Creare le impostazioni di diagnostica per inviare le metriche e i log della piattaforma a destinazioni diverse.

Visualizzare i dati di diagnostica in Monitoraggio di Azure

Se si abilita la raccolta di log o metriche in un'area di lavoro Log Analytics, la visualizzazione dei dati in Monitoraggio di Azure può richiedere alcuni minuti.

Per visualizzare i dati:

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

  2. Selezionare Log dal menu a sinistra.

    Screenshot della voce Log nel menu Monitoraggio nel portale.

  3. Eseguire query per visualizzare i dati. Sono disponibili numerose query di esempio oppure eseguire una query personalizzata. Ad esempio, la query seguente recupera le ultime 24 ore di dati dalla tabella ApiManagementGatewayLogs:

    ApiManagementGatewayLogs
| where TimeGenerated > ago(1d)

    Screenshot dell'esecuzione di query sulla tabella ApiManagementGatewayLogs nel portale.

Per altre informazioni sull'utilizzo dei log delle risorse per Gestione API, vedere:

Modificare le impostazioni di registrazione API

Per impostazione predefinita, quando si crea un'impostazione di diagnostica per abilitare la raccolta di log delle risorse, la registrazione è abilitata per tutte le API, con le impostazioni predefinite. È possibile modificare le impostazioni di registrazione per tutte le API o eseguirne l'override per le singole API. Ad esempio, regolare la frequenza di campionamento o il livello di dettaglio dei dati o disabilitare la registrazione per alcune API.

Per informazioni dettagliate sulle impostazioni di registrazione, vedere Informazioni di riferimento sulle impostazioni di registrazione diagnostica.

Per configurare le impostazioni di registrazione per tutte le API:

  1. Nel menu a sinistra dell'istanza di Gestione API selezionare API Tutte le>API.
  2. Selezionare la scheda Impostazioni nella barra superiore.
  3. Scorrere verso il basso fino alla sezione Log di diagnostica e selezionare la scheda Monitoraggio di Azure.
  4. Esaminare le impostazioni e apportare modifiche, se necessario. Seleziona Salva.

Per configurare le impostazioni di registrazione per un'API specifica:

  1. Nel menu a sinistra dell'istanza di Gestione API selezionare API e quindi il nome dell'API.
  2. Selezionare la scheda Impostazioni nella barra superiore.
  3. Scorrere verso il basso fino alla sezione Log di diagnostica e selezionare la scheda Monitoraggio di Azure.
  4. Esaminare le impostazioni e apportare modifiche, se necessario. Seleziona Salva.

Passaggi successivi

Questa esercitazione ha descritto come:

  • Visualizzare le metriche dell'API
  • Configurare una regola di avviso
  • Visualizzare i log attività
  • Abilitare e visualizzare i log delle risorse

Passare all'esercitazione successiva:

Tracciare le chiamate