Utilizzo dell'API delle metriche

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza 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 utile per il monitoraggio operativo e aziendale. Con Apigee Analytics, puoi, ad esempio, Ad esempio, stabilire quali API hanno prestazioni soddisfacenti o scarse, quali sviluppatori offrono di valore più elevato e le app che causano il maggior numero di problemi per i tuoi servizi di backend.

Per accedere facilmente ai dati di queste metriche, utilizza l'API Metrics quando devi automatizzare alcuni funzioni di analisi, come il recupero di metriche periodicamente utilizzando un client o uno script per l'automazione. Puoi anche utilizzare l'API per creare il tuo visualizzazioni 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 per un'organizzazione e un ambiente per un determinato 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 l'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 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 metriche da recuperare e una funzione di aggregazione facoltativa, nella forma:

    ?select=metric

    oppure:

    ?select=aggFunction(metric)

    Dove:

    • metric specifica i dati che vuoi restituire. Ad esempio: il numero di richieste API, i successi della cache o gli errori dei criteri. Consulta le 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 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 su 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. Il prossimo esempio 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. a ottenere metriche con la somma degli errori dei criteri e la dimensione media della richiesta, imposta il parametro di query select utilizzando elenco di metriche:

    ?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. Usa timeRange (massimo 6 mesi) per specificare il periodo di tempo, nella forma:

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

    Osserva %20 prima di HH:MM. Il parametro timeRange richiede uno spazio con codifica URL prima di HH:MM o 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 ulteriori 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 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, vedi Con 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 metriche per il numero di richieste ricevute da tutti i proxy API nell'arco di due giorni. Il parametro di query select definisce la funzione aggregata 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/6/2018 e la fine del 21/6/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, vedi Con 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 "target-reroute" in esecuzione nell'ambiente di test tra l'inizio del 20/6/2018 e la fine 21/06/2018.

    Per ottenere metriche per altre dimensioni, specifica una dimensione diversa come parametro URI. Per Ad esempio, puoi specificare la dimensione developer_app per recuperare le metriche per 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 e i dati di Google Cloud. Di solito, è necessario ottenere i risultati per le "primi 10", ad esempio i "primi 10 più lenti API", le "10 app più attive". Puoi farlo utilizzando il parametro di query topk nell'ambito della richiesta.

    Ad esempio, potrebbe interessarti sapere chi sono i tuoi migliori sviluppatori, misurati in termini di velocità effettiva, o gli elementi 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 con il valore più alto per una determinata metrica. In questo modo puoi filtrare le metriche per un elenco entità che rappresentano una particolare condizione.

    Ad esempio, per trovare l'URL di destinazione con il maggiore rischio di errori nell'ultima settimana, il parametro topk viene aggiunto alla richiesta, 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 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, vedi Con 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 più bug http://api.company.com.

    Puoi anche utilizzare il parametro topk per ordinare in base alle API con il tasso e la velocità effettiva effettiva. L'esempio seguente recupera le metriche nell'API con il ranking più alto, definita dal criterio 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 si utilizza devi utilizzare le dimensioni come proprietà di filtro.

    Supponiamo, ad esempio, che tu debba recuperare un conteggio di errori dai servizi di backend e viene filtrato in base al verbo HTTP della richiesta. Il tuo obiettivo è scoprire quante richieste POST e PUT generando errori per ogni servizio di backend. Per farlo, devi utilizzare 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, vedi Con 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 dati molto grandi set di dati. Per semplificare la visualizzazione di set di dati di grandi dimensioni nel contesto di un'applicazione basata su UI, L'API supporta l'impaginazione in modo nativo.

    Per impaginare i risultati, usa i parametri di ricerca offset e limit, insieme al parametro di ordinamento sortby per garantire un ordine coerente delle 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 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, vedi Con 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 a 50. Poiché 0 viene conteggiato come primo elemento, la chiamata seguente restituisce gli elementi 0-49 in ordine decrescente ordine predefinito (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 offset, come segue. Tieni presente che limite e offset sono identici. Questo perché 0 viene conteggiato come primo elemento. Con un limite di 50 e e un offset pari a 0, vengono restituiti gli elementi da 0 a 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"