Utilizzo dell'API delle metriche

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Apigee registra un'ampia gamma di dati operativi e aziendali che passano per le API. Le metriche derivate da questi dati sono utili per il monitoraggio operativo e aziendale. Utilizzando Apigee Analytics, puoi, ad esempio, determinare quali API hanno prestazioni soddisfacenti o insufficienti, quali sviluppatori offrono il traffico di maggiore valore e quali app causano il maggior numero di problemi per i 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 utilizzando 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 scoprire come utilizzare Analytics nell'interfaccia utente di Apigee, consulta la panoramica di Apigee Analytics.

Informazioni sull'API delle metriche

Esistono due modi per utilizzare l'API Metrics:

  • Visualizza le metriche per un'organizzazione e un ambiente in 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 e email dello sviluppatore (che può essere anche un ID AppGroup) per ottenere:

    • Numero di errori dei criteri per prodotto API
    • Tempo medio di risposta per proxy API
    • Traffico totale per email dello sviluppatore

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

    Per saperne di più, consulta il riferimento API delle metriche.

    Inizia a utilizzare l'API delle metriche

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

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

    Ad esempio, per ottenere 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 le metriche non elaborate per l'intera organizzazione e l'intero 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 delle metriche da restituire

    Utilizza il parametro di query select per specificare le metriche 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, hit della cache o errori delle norme. Consulta la sezione Metriche 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 Latenza di elaborazione:

      • avg: restituisce la latenza media di elaborazione.
      • min: restituisce la latenza minima di elaborazione.
      • max: Restituisce la latenza di elaborazione massima.
      • sum: restituisce la somma di tutte le latenze di elaborazione.
      • p50: restituisce il 50° percentile per le latenze di elaborazione, calcolato utilizzando percentile(latency_metric,50)&aggTable=agg_percentile.
      • p95: restituisce il 95° percentile per le latenze di elaborazione, calcolato utilizzando percentile(latency_metric,95)&aggTable=agg_percentile.
      • p99: restituisce il 99° percentile per le latenze di elaborazione, calcolato utilizzando percentile(latency_metric,99)&aggTable=agg_percentile.

      Il latency_metric può essere:

      • total_response_time
      • target_response_time
      • response_processing_latency
      • request_processing_latency

      Non tutte le metriche supportano tutte le funzioni di aggregazione. La documentazione sulle metriche 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, ovvero richieste proxy API, al secondo: 

    ?select=tps

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

    ?select=sum(cache_hit)

    Puoi restituire più metriche per una singola chiamata API. Per ottenere le metriche per la somma degli errori delle norme e la dimensione media delle richieste, 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 per 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

    Nota %20 prima di HH:MM. Il parametro timeRange richiede un carattere di spazio codificato nell'URL prima di HH:MM o un carattere +, come in: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

    Ad esempio:

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

    Non utilizzare le 24:00 come orario perché viene riportato alle 00:00. Utilizza invece 23:59.

    Esempi di chiamata dell'API delle metriche

    Questa sezione fornisce esempi di utilizzo dell'API delle metriche. Per altri esempi, consulta Esempi di API delle metriche.

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

    Per restituire il numero totale di chiamate effettuate a tutte le API nella tua organizzazione e nel tuo ambiente per 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 tuo 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 la sezione Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

    Di seguito è riportato un esempio di risposta:

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

    Restituisce il conteggio totale dei messaggi per proxy API per due giorni

    In questo esempio, restituisci 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 di aggregazione sum per la metrica message_count sulla 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, in ora 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 tuo 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 la sezione Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

    Di seguito è riportato un esempio di 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 "target-reroute" 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 il throughput 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 è riportato un esempio di 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"
        }
  ]...
}

    Ordinare i risultati in base al ranking relativo

    Molte volte, quando ottieni le metriche, vuoi solo ottenere risultati per un sottoinsieme del set totale di dati. In genere, devi ottenere i risultati per le "prime 10", ad esempio le "10 API più lente" o le "10 app più attive". Puoi farlo utilizzando il parametro di query topk come parte della richiesta.

    Ad esempio, potresti essere interessato a sapere chi sono i tuoi migliori sviluppatori, misurati in base al throughput, o quali sono i tuoi peggiori rendimenti (ad es. "più lente") sono ordinate in base alla latenza.

    topk (ovvero le prime k entità) 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 esemplificano una determinata condizione.

    Ad esempio, per scoprire quale URL di destinazione ha generato il maggior numero di errori nell'ultima settimana, il parametro topk viene aggiunto alla richiesta con un valore di 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 tuo 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 la sezione Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

    Di seguito è riportato un esempio di 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 mostrano che l'URL di destinazione con più bug è http://api.company.com.

    Puoi anche utilizzare il parametro topk per ordinare le API con il throughput più elevato. L'esempio seguente recupera le metriche dell'API con il ranking più alto, definito dal throughput più elevato nell'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 è riportato un esempio di 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

    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 di dover recuperare un conteggio degli errori dai servizi di backend filtrati in base al verbo HTTP della richiesta. Il tuo obiettivo è scoprire quante richieste POST e PUT generano errori per servizio di backend. A tal fine, 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 tuo 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 la sezione Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

    Di seguito è riportato un esempio di risposta:

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

    Impaginazione dei risultati

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

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

    Ad esempio, la seguente richiesta probabilmente restituirà un set di dati di grandi dimensioni, poiché recupera le metriche per tutti gli errori su tutte le API nell'ambiente di produzione dell'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 tuo 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 la sezione Utilizzare curl. Per una descrizione delle variabili di ambiente utilizzate, consulta Impostazione delle variabili di ambiente per le richieste API Apigee.

    Se la tua applicazione basata sulla UI può visualizzare ragionevolmente 50 risultati per pagina, puoi impostare il limite su 50. Poiché 0 viene conteggiato come il primo elemento, la seguente chiamata 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" di risultati, utilizza il parametro di query offset, come segue. Tieni presente che il limite e l'offset sono identici. Questo perché 0 viene conteggiato come il primo elemento. Con un limite di 50 e un offset di 0, vengono restituiti gli elementi da 0 a 49. Con un offset di 50, vengono restituiti gli elementi da 50 a 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"