Utilizzo dell'API delle metriche

Questa pagina si applica a Apigee e Apigee ibrido.

Visualizza la documentazione di Apigee Edge.

Apigee registra un'ampia varietà di dati operativi e aziendali che passano per le API. Le metriche derivate da questi dati sono utili per il monitoraggio operativo e aziendale. Con Apigee Analytics, puoi, ad esempio, determinare quali API hanno prestazioni soddisfacenti o scadenti, quali sviluppatori forniscono il traffico di valore più elevato e quali app causano il maggior numero di problemi ai tuoi servizi di backend.

Per accedere facilmente a questi dati delle metriche, utilizza l'API Metrics quando devi automatizzare determinate funzioni di analisi, ad esempio il recupero periodico delle metriche tramite un client o uno script di automazione. Puoi anche utilizzare l'API per creare visualizzazioni personalizzate sotto forma di widget personalizzati che puoi incorporare in portali o app personalizzate.

Per informazioni su come utilizzare Analytics nella UI di Apigee, consulta la panoramica di Apigee Analytics.

Informazioni sull'API Metrics

Esistono due modi per utilizzare l'API Metrics:

  • Visualizza le metriche relative a un'organizzazione e un ambiente per un periodo di tempo, ad esempio un'ora, un giorno o una settimana. Questo metodo restituisce metriche non elaborate per l'intera organizzazione e l'intero ambiente.

    Ad esempio, per la settimana precedente, vuoi ottenere:

    • Numero di errori dei criteri
    • Tempo medio di risposta
    • Traffico totale

  • Visualizza le metriche organizzate per dimensione in un periodo di tempo per un'organizzazione e un ambiente.

    Ad esempio, per la settimana precedente puoi utilizzare le dimensioni per raggruppare le metriche per prodotto API, proxy API ed email dello sviluppatore (che può anche essere un ID AppGroup) per ottenere:

    • Numero di errori relativi alle norme per prodotto API
    • Tempo di risposta medio per proxy API
    • Traffico totale per email sviluppatore

    Per gestire il risultato restituito, l'API Metrics supporta le seguenti funzionalità:

    Per ulteriori informazioni, consulta il riferimento dell'API delle metriche.

    Inizia a utilizzare l'API Metrics

    L'URL della richiesta per l'API Metrics è:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    Ad esempio, per ottenere le metriche raggruppate per proxy API, utilizza il seguente URL per chiamare l'API Apigee:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

    Ometti la dimensione per restituire metriche non elaborate per l'intera organizzazione e l'ambiente per il periodo di tempo specificato:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    Specifica le metriche da restituire

    Utilizza il parametro di query select per specificare le metrics da recuperare e una funzione di aggregazione facoltativa, nel formato:

    ?select=metric

    oppure:

    ?select=aggFunction(metric)

    Dove:

    • metric specifica i dati che vuoi restituire. Ad esempio, il numero di richieste API, i hit della cache o gli errori dei criteri. Consulta la sezione metrics per una tabella che specifica il nome della metrica da utilizzare con il parametro di query select.

    • aggFunction specifica la funzione di aggregazione facoltativa eseguita sulla metrica. Ad esempio, puoi utilizzare le seguenti funzioni di aggregazione con la metrica della latenza di elaborazione:

      • avg: restituisce la latenza media di elaborazione.
      • min: restituisce la latenza di elaborazione minima.
      • max: restituisce la latenza massima di elaborazione.
      • sum: restituisce la somma di tutte le latenze di elaborazione.
      • p50: restituisce il 50° percentile per le latenze di elaborazione.
      • p95: restituisce il 95° percentile per le latenze di elaborazione.
      • p99: restituisce il 99° percentile per le latenze di elaborazione.

      Non tutte le metriche supportano tutte le funzioni di aggregazione. La documentazione sulle metrics contiene una tabella che specifica il nome della metrica e la funzione (sum, avg, min, max) supportata dalla metrica.

    Ad esempio, per restituire il numero medio di transazioni al secondo, ovvero richieste proxy API: 

    ?select=tps

    Tieni presente che questo esempio non richiede una funzione di aggregazione. L'esempio seguente utilizza una funzione di aggregazione per restituire la somma di hit della cache:

    ?select=sum(cache_hit)

    Puoi restituire più metriche per una singola chiamata API. Per ottenere le metriche relative alla somma degli errori dei criteri e alle dimensioni medie della richiesta, imposta il parametro di query select utilizzando un elenco di metriche separate da virgole:

    ?select=sum(policy_error),avg(request_size)

    Specificare il periodo di tempo

    L'API Metrics restituisce i dati relativi a un periodo di tempo specificato. Utilizza il parametro di query timeRange (massimo 6 mesi) per specificare il periodo di tempo, nel formato:

    ?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

    Osserva %20 prima di HH:MM. Il parametro timeRange richiede un carattere spazio con codifica URL prima di HH:MM oppure un carattere +, ad esempio MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

    Ad esempio:

    ?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

    Non usare le 24:00 come ora perché finiscono per le 00:00. Usa invece 23:59.

    Esempi di chiamata all'API Metrics

    Questa sezione fornisce esempi di utilizzo dell'API Metrics. Per altri esempi, consulta gli esempi di API Metrics.

    Restituisci il numero totale di chiamate effettuate alle tue API per un mese

    Per restituire il numero totale di chiamate effettuate a tutte le API nell'organizzazione e nell'ambiente nell'arco di un mese, utilizza una chiamata simile alla seguente:

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le variabili di ambiente per le richieste API Apigee.

    Di seguito viene fornito un esempio della risposta:

    {
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

    Restituisci il numero totale di messaggi per proxy API per due giorni

    In questo esempio, vengono restituite le metriche per il numero di richieste ricevute da tutti i proxy API in un periodo di due giorni. Il parametro di query select definisce la funzione aggregata sum per la metrica message_count nella dimensione apiproxy. Il report restituisce la velocità effettiva dei messaggi di richiesta per tutte le API per il traffico ricevuto tra l'inizio del 20/06/2018 e la fine del 21/06/2018, nel fuso orario UTC:

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le variabili di ambiente per le richieste API Apigee.

    Di seguito viene fornito un esempio della risposta:

    {
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

    Questa risposta indica che sono stati ricevuti 1100 messaggi da un proxy API chiamato "rerouter target" in esecuzione nell'ambiente di test tra l'inizio del 20/06/2018 e la fine del 21/06/2018.

    Per ottenere metriche per altre dimensioni, specifica una dimensione diversa come parametro URI. Ad esempio, puoi specificare la dimensione developer_app per recuperare le metriche per le app per sviluppatori. La seguente chiamata API restituisce la velocità effettiva totale (messaggi ricevuti) da qualsiasi app per l'intervallo di tempo specificato:

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    Di seguito viene fornito un esempio della risposta:

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "886.0"
                }
              ]
            }
          ],
          "name": "Test-App"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "6645.0"
                }
              ]
            }
          ],
          "name": "johndoe_app"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "1109.0"
                }
              ]
            }
          ],
          "name": "marys_app"
        }
  ]...
}

    Ordinamento dei risultati per ranking relativo

    Spesso, quando visualizzi le metriche, vuoi ottenere risultati solo per un sottoinsieme dell'insieme totale di dati. Di solito, è necessario ottenere i risultati per le "prime 10", ad esempio le "prime 10 API più lente", le "prime 10 app più attive". Puoi farlo utilizzando il parametro di query topk come parte della richiesta.

    Ad esempio, potrebbe interessarti sapere chi sono i tuoi sviluppatori migliori, misurati in base alla velocità effettiva, o quali sono gli sviluppatori con il rendimento peggiore (ad es. le API di destinazione "più lente") sono per latenza.

    topk (ovvero le entità "top k") consente di generare report sulle entità associate al valore più alto per una determinata metrica. In questo modo puoi filtrare le metriche per un elenco di entità che rappresentano una determinata condizione.

    Ad esempio, per trovare quale URL di destinazione è stato il più soggetto a errori nell'ultima settimana, alla richiesta viene aggiunto il parametro topk, con il valore 1:

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
  -H "Authorization: Bearer $TOKEN"

    Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le variabili di ambiente per le richieste API Apigee.

    Di seguito viene fornito un esempio della risposta:

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(is_error)",
              "values": [
                {
                  "timestamp": 1494201600000,
                  "value": "12077.0"
                }
              ]
            }
          ],
          "name": "http://api.company.com"
        }
      ]...
}

    Il risultato di questa richiesta è un insieme di metriche che mostra che l'URL di destinazione con più bug è http://api.company.com.

    Puoi anche utilizzare il parametro topk per ordinare le API con la velocità effettiva più elevata. L'esempio seguente recupera le metriche nell'API con il ranking più elevato, definita dalla velocità effettiva più elevata dell'ultima settimana:

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
  -H "Authorization: Bearer $TOKEN"

    Di seguito viene fornito un esempio della risposta:

    {
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1494720000000,
                  "value": "5750.0"
                },
                {
                  "timestamp": 1494633600000,
                  "value": "5752.0"
                },
                {
                  "timestamp": 1494547200000,
                  "value": "5747.0"
                },
                {
                  "timestamp": 1494460800000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494374400000,
                  "value": "5753.0"
                },
                {
                  "timestamp": 1494288000000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494201600000,
                  "value": "5752.0"
                }
              ]
            }
          ],
          "name": "testCache"
        }
      ],
      "name": "test"
    }
  ]...
}

    Filtro dei risultati in corso...

    Per una maggiore granularità, puoi filtrare i risultati per limitare i dati restituiti. Quando utilizzi i filtri, devi utilizzare le dimensioni come proprietà di filtro.

    Ad esempio, supponiamo che tu debba recuperare un conteggio degli errori dai servizi di backend filtrato in base al verbo HTTP della richiesta. Il tuo obiettivo è scoprire quante richieste POST e PUT generano errori per servizio di backend. Per farlo, utilizza la dimensione target_url insieme al filtro request_verb:

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
  -H "Authorization: Bearer $TOKEN"

    Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le variabili di ambiente per le richieste API Apigee.

    Di seguito viene fornito un esempio della risposta:

    {
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

    Impaginazione dei risultati

    In ambienti di produzione, alcune richieste all'API di analisi Apigee restituiscono set di dati molto grandi. Per semplificare la visualizzazione di set di dati di grandi dimensioni nel contesto di un'applicazione basata sulla UI, l'API supporta l'impaginazione in modo nativo.

    Per impaginare i risultati, utilizza i parametri di ricerca offset e limit, insieme al parametro di ordinamento sortby, per garantire un ordinamento coerente degli elementi.

    Ad esempio, è probabile che la seguente richiesta restituisca un set di dati di grandi dimensioni, poiché recupera le metriche relative a tutti gli errori relativi a tutte le API nell'ambiente del prodotto per l'ultima settimana.

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    Dove $TOKEN è impostato sul token di accesso OAuth 2.0, come descritto in Ottenere un token di accesso OAuth 2.0. Per informazioni sulle opzioni curl utilizzate in questo esempio, consulta Utilizzo di curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostare le variabili di ambiente per le richieste API Apigee.

    Se la tua applicazione basata su UI può visualizzare ragionevolmente 50 risultati per pagina, puoi impostare il limite su 50. Poiché 0 viene conteggiato come primo elemento, la chiamata seguente restituisce gli elementi da 0 a 49 in ordine decrescente (sort=DESC è il valore predefinito).

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"

    Per la seconda "pagina" dei risultati, utilizza il parametro di query dell'offset come segue. Tieni presente che il limite e l'offset sono identici. Questo perché 0 viene conteggiato come primo elemento. Con un limite di 50 e un offset di 0, vengono restituiti gli elementi tra 0 e 49. Con uno scarto pari a 50, vengono restituiti gli articoli 50-99.

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
  -H "Authorization: Bearer $TOKEN"