Stai visualizzando la documentazione di Apigee Edge.
Vai alla
documentazione di Apigee X. informazioni
Apigee Edge registra un'ampia varietà di dati operativi e aziendali che passano attraverso le API. Le metriche derivate da questi dati sono utili per il monitoraggio operativo e aziendale. Utilizzando Analisi delle API Edge, puoi, ad esempio, determinare quali API hanno prestazioni buone o scarse, quali sviluppatori offrono il traffico di maggior valore e quali app causano il maggior numero di problemi per i servizi di backend.
Per facilitare l'accesso a questi dati delle metriche, Edge espone un'API RESTful. Puoi utilizzare l'API delle metriche quando devi automatizzare determinate funzioni di Analytics, ad esempio recuperare periodicamente le metriche utilizzando un client o uno script di automazione. Puoi anche utilizzare l'API per creare le tue visualizzazioni sotto forma di widget personalizzati che puoi incorporare in portali o app personalizzate.
Per scoprire come utilizzare Analytics nell'interfaccia utente di gestione perimetrale delle API, consulta la panoramica dell'analisi delle API.
Informazioni sulle API delle metriche
Edge fornisce due API per le metriche:
Recupera metriche restituisce le metriche per un'organizzazione e un ambiente relativi a un periodo di tempo, ad esempio un'ora, un giorno o una settimana.
Ad esempio, per la settimana precedente vuoi ottenere:
- Il numero di errori dei criteri
- Il tempo medio di risposta
- Il traffico totale
Ottieni metriche organizzate per dimensioni restituisce le metriche relative a un periodo di tempo per un'organizzazione e un ambiente raggruppati per dimensione.
Ad esempio, per la settimana precedente hai utilizzato le dimensioni per raggruppare le metriche per prodotto API, proxy API ed email dello sviluppatore per ottenere:
- Il numero di errori relativi alle norme per prodotto API
- Il tempo di risposta medio per proxy API
- Il traffico totale per email sviluppatore
L'API Ottieni metriche organizzate per dimensioni supporta funzionalità aggiuntive non supportate dall'API Ottieni metriche, tra cui:
Informazioni sulle quote dell'API delle metriche
Edge applica le quote seguenti a queste chiamate. La quota si basa sul sistema di backend che gestisce la chiamata:
- Postgres: 40 chiamate al minuto
- BigQuery: 12 chiamate al minuto
Determina il sistema di backend che gestisce la chiamata esaminando l'oggetto della risposta.
Ogni oggetto risposta contiene una proprietà metaData che elenca il servizio che ha gestito la chiamata
nella proprietà Source. Ad esempio, per Postgres:
{
...
"metaData": {
"errors": [],
"notices": [
"Source:Postgres",
"Table used: xxxxxx.yyyyy",
"query served by:111-222-333"
]
}
}
Per BigQuery, la proprietà Source è:
"Source:Big Query"
Se superi la quota di chiamate, l'API restituisce una risposta HTTP 429.
Recupero delle metriche con l'API di gestione
La differenza principale tra le due API è che Ottieni metriche restituisce metriche non elaborate per l'intera organizzazione e l'ambiente, mentre Ottieni metriche organizzate per dimensioni ti consente di raggruppare le metriche in base a diversi tipi di entità, ad esempio prodotto API, sviluppatore e app.
L'URL della richiesta per l'API Ottieni metriche è:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats
Per l'API Visualizza le metriche organizzate per dimensioni, includi una risorsa aggiuntiva all'URL dopo il giorno /stats che specifica la dimensione desiderata:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension
Ad esempio, per raggruppare le metriche per proxy API, devi utilizzare il seguente URL per chiamare l'API di gestione:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy
Specifica delle metriche da restituire
Per le API Ottieni metriche e Ottieni metriche organizzate in base alle dimensioni, 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, hit della cache o 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 in base alla metrica. Ad esempio, puoi utilizzare le seguenti funzioni di aggregazione con la metrica relativa alla latenza di elaborazione:
avg: restituisce la latenza media di elaborazione.min: restituisce la latenza minima di elaborazione.max: restituisce la latenza massima di elaborazione.-
sum: restituisce la somma di tutte 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 le richieste proxy API:
?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 metriche per la somma degli errori dei criteri e delle dimensioni medie 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 delle metriche restituisce i dati per un periodo di tempo specificato. Utilizza il parametro di query timeRange per specificare il periodo di tempo nel formato:
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
Osserva il %20 prima del giorno HH:MM. Il parametro timeRange richiede uno spazio con codifica URL prima di HH:MM o un carattere +, come 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 24:00 come ora, perché finisce intorno a 00:00. In alternativa, utilizza il formato 23:59.
Utilizzo di un delimitatore
Per separare più dimensioni in una chiamata API, utilizza una virgola (,) come delimitatore.
Ad esempio, nella chiamata API
curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day
le dimensioni apis e apps sono separate da ,.
Chiamate API di esempio
Questa sezione contiene esempi che utilizzano le API Ottieni metriche e Ottieni metriche organizzate per dimensioni. Per ulteriori esempi, consulta gli esempi di API delle metriche.
Restituisci il numero totale di chiamate effettuate alle tue API in un mese
Per visualizzare il numero totale di chiamate effettuate a tutte le API nella tua organizzazione e nel tuo ambiente per un mese, utilizza l'API Get Metrics:
curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password
Esempio di risposta:
{
"environments": [
{
"metrics": [
{
"name": "sum(message_count)",
"values": [
"7.44944088E8"
]
}
],
"name": "prod"
}
],
...
}
Restituire il numero totale di messaggi per proxy API per due giorni
In questo esempio, vengono restituite le metriche relative al 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://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password
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/6/2018 e la fine del 21/06/2018.
Per visualizzare le 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 degli sviluppatori. La seguente chiamata API restituisce la velocità effettiva totale (messaggi ricevuti) da qualsiasi app per l'intervallo di tempo specificato:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password
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"
}
]...
}
Ordinamento dei risultati per ranking relativo
Molte volte, quando ottieni metriche, vuoi ottenere risultati solo per un sottoinsieme dell'insieme totale di dati. In genere è necessario ottenere i risultati per le "prime 10", ad esempio, le "10 API più lente", le "10 app più attive". Puoi farlo utilizzando il parametro di query topk all'interno della richiesta.
Ad esempio, potrebbe interessarti sapere chi sono i tuoi migliori sviluppatori, se misurati in base alla velocità effettiva o quali sono quelli con il rendimento peggiore (ad es. le API target "più lente") sono calcolate in base alla latenza.
topk (ovvero entità "top k") consente di generare report sulle entità associate
con il valore più alto per una determinata metrica. Ciò consente di filtrare le metriche per un elenco di entità che esemplificano una determinata condizione. Ad esempio, per trovare quale URL di destinazione è stato il più soggetto a errori nell'ultima settimana, il parametro topk viene aggiunto alla richiesta, con il valore 1:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password
{
"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 più errato è
http://api.company.com.
Puoi anche utilizzare il parametro topk per ordinare le API che utilizzano la velocità effettiva più elevata. L'esempio seguente recupera le metriche sull'API con il ranking più alto, definite dalla velocità effettiva più elevata nell'ultima settimana:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password
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 risultati
Per una maggiore granularità, puoi filtrare i risultati per limitare i dati restituiti. Quando utilizzi i filtri, devi usare le dimensioni come proprietà di filtro.
Ad esempio, supponi di dover recuperare un conteggio di 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. Per farlo, utilizza la dimensione target_url insieme al filtro request_verb:
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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')" \
-u email:password
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 Edge 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 l'impaginazione.
Per impaginare i risultati, utilizza i parametri di query offset e limit, insieme al parametro di ordinamento sortby per garantire un ordine coerente degli elementi.
Ad esempio, la seguente richiesta potrebbe restituire un set di dati di grandi dimensioni, poiché recupera le metriche per tutti gli errori in tutte le API nell'ambiente del prodotto per l'ultima settimana.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password
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 successiva restituisce gli elementi da 0 a 49 in ordine decrescente (sort=DESC è l'impostazione predefinita).
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password
Per la seconda "pagina" dei risultati, utilizza il parametro di query offset come indicato di seguito. 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 da 0 a 49. Con un offset di 50, vengono restituiti gli elementi da 50 a 99.
curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{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" \
-u email:password