Stai visualizzando la documentazione di Apigee Edge.
Consulta la
documentazione di Apigee X. info
Apigee Edge registra una vasta 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 Edge API Analytics, puoi, ad esempio, determinare quali API hanno prestazioni soddisfacenti o insufficienti, quali sviluppatori offrono il traffico di maggiore valore e quali app causano la maggior parte dei 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 uno script o un client 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 gestione di API Edge, consulta la panoramica di API Analytics.
Informazioni sulle API delle metriche
Edge fornisce due API delle metriche:
L'API Get metrics restituisce le metriche per un'organizzazione e un ambiente in 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 di risposta medio
- Il traffico totale
L'API Get metrics organized by dimensions restituisce le metriche in un periodo di tempo per un'organizzazione e un ambiente raggruppate per dimensione.
Ad esempio, per la settimana precedente utilizzi le dimensioni per raggruppare le metriche per prodotto API, proxy API, ed email dello sviluppatore per ottenere:
- Il numero di errori dei criteri per prodotto API
- Il tempo di risposta medio per proxy API
- Il traffico totale per email dello sviluppatore
L'API Get metrics organized by dimensions supporta funzionalità aggiuntive non supportate dall'API Get metrics, tra cui:
Informazioni sulle quote delle API delle metriche
Edge applica le seguenti quote 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 della 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.
Recuperare le metriche con l'API di gestione
La differenza principale tra le due API è che Get metrics restituisce le metriche non elaborate per l'intera organizzazione e l'intero ambiente, mentre Get metrics organized by dimensions consente di raggruppare le metriche per diversi tipi di entità, come prodotto API, sviluppatore e app.
L'URL della richiesta per l'API Get metrics è:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/statsPer l'API Get metrics organized by dimensions
includi una risorsa aggiuntiva nell'URL dopo /stats che specifica la dimension desiderata:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimensionAd esempio, per ottenere le metriche raggruppate per proxy API, utilizzeresti il seguente URL per chiamare l'API di gestione:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxySpecificare le metriche da restituire
Per le API Get metrics e Get metrics organized by dimensions utilizzi 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 dei criteri. Consulta la tabella delle metriche
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 di elaborazione media.min: restituisce la latenza di elaborazione minima.max: restituisce la latenza di elaborazione massima.-
sum: restituisce la somma di tutte le latenze di elaborazione.
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 di proxy API, al secondo:
?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 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 dei criteri
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 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
Nota %20 prima di HH:MM. Il parametro timeRange richiede un carattere 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 24:00 come ora perché viene eseguito il wrapping fino a 00:00. Utilizza invece 23:59.
Utilizzare 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 ,.
Esempi di chiamate API
Questa sezione contiene esempi che utilizzano le API Get metrics e Get metrics organized by dimensions. Per altri esempi, consulta Esempi di API Metrics.
Restituire il numero totale di chiamate effettuate alle API per 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 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 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, in
ora 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 1100 messaggi sono stati ricevuti da un proxy API denominato "target-reroute" in esecuzione nell'ambiente di test tra l'inizio del 20/06/2018 e la fine del 21/06/2018.
Per ottenere 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 per 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:passwordEsempio 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 alla classificazione relativa
Molte volte, quando recuperi le metriche, vuoi ottenere i risultati solo per un sottoinsieme dell'insieme totale di
dati. In genere, devi ottenere i risultati per i "primi 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 quali sono i tuoi migliori sviluppatori, misurati in base alla velocità effettiva, o quali sono le API di destinazione con le prestazioni peggiori (ovvero "le più lente") in base alla latenza.
Il topk (che significa "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 condizione specifica. Ad esempio, per scoprire quale URL di destinazione ha generato più errori nell'ultima settimana, il parametro topk viene aggiunto alla richiesta con un valore di 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 mostra che l'URL di destinazione più problematico è
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 per l'API con la classificazione più alta, definita 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"
}
]...
}Filtrare i 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 che tu debba 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. Per farlo, utilizzi 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"
}
]...
}Impaginare i risultati
Negli ambienti di produzione, alcune richieste all'API di analisi di Edge restituiscono set di dati molto grandi. Per facilitare la visualizzazione di set di dati di grandi dimensioni nel contesto di un'applicazione basata sull'interfaccia utente, la API supporta in modo nativo la paginazione.
Per impaginare i risultati, utilizza i parametri di query offset e limit,
insieme al parametro di ordinamento sortby per garantire un ordinamento 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 su tutte le API nell'ambiente di produzione 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 sull'interfaccia utente può visualizzare ragionevolmente 50 risultati per pagina, puoi impostare il limite
su 50. Poiché 0 conta come il primo elemento, la seguente chiamata restituisce gli elementi 0-49 in ordine decrescente (sort=DESC è il valore predefinito).
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 segue. Tieni presente che il limite e l'offset sono identici. Questo perché 0 conta come il primo elemento. Con un limite di 50 e un offset di 0, vengono restituiti gli elementi 0-49. Con un offset di 50, vengono restituiti gli elementi 50-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