Condividi tramite

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.

Nota

Attualmente, questa funzionalità non è disponibile nelle aree di lavoro.

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 metriche usate più di frequente. Per un elenco di tutte le metriche disponibili, vedere Metriche supportate.

  • Capacità: consente di decidere se eseguire l'aggiornamento o il downgrade dei servizi di Gestione API. La metrica viene emessa ogni minuto e riflette la capacità del gateway stimate al momento in cui viene eseguito il report. La metrica è compresa tra 0 e 100 e viene calcolata in base alle risorse gateway, come utilizzo della CPU e della memoria e altri fattori.

    Suggerimento

    Nei livelli di servizio v2, Gestione API ha sostituito la metrica della capacità con metriche di utilizzo della CPU e della memoria separate. Queste metriche possono essere usate anche per decisioni di ridimensionamento e risoluzione dei problemi. Ulteriori informazioni

  • 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 seguenti metriche sono state ritirate: totale richieste gateway, richieste gateway riuscite, richieste gateway non autorizzate, richieste gateway non riuscite, altre richieste 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 pagina di panoramica, nella scheda Monitoraggio 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. Dall'elenco a discesa selezionare le metriche desiderate. 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, quindi selezionare Backend Response Code Category (Categoria codice di risposta back-end) e immettere 500 come valore. Il grafico mostra ora 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 avviso, specificare un Valore soglia , ovvero il numero di occorrenze dopo cui 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à offrono 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 di 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 di 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. Per esempio, è possibile archiviare i log delle risorse con le metriche in un account di archiviazione, trasmetterli in streaming 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 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 le destinazioni o la destinazioni del log, selezionare Salva.

Nota

L'aggiunta di un oggetto impostazione di diagnostica potrebbe causare un errore se la proprietà MinApiVersiondel servizio Gestione API è impostata su qualsiasi versione 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, potrebbero essere necessari alcuni minuti prima che i dati vengano visualizzati in Monitoraggio di Azure.

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 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, abilitare la registrazione di intestazioni o payload di richiesta o risposta 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 dalla barra in alto.
  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 dalla barra in alto.
  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.

Importante

Se abilitata, i payload di richiesta o risposta registrati possono raggiungere 8.192 byte. Gestione API applica anche un limite di 32 kB per una voce di log di diagnostica inviata a Monitoraggio di Azure, che include i payload e altri attributi, ad esempio codici di stato, intestazioni e timestamp. Se le dimensioni combinate degli attributi superano i 32 kB, Gestione API taglia la voce rimuovendo tutto il contenuto del corpo e della traccia.

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