Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen
Apigee Edge zeichnet eine Vielzahl von Betriebs- und Geschäftsdaten auf, die über APIs übertragen werden. Die aus diesen Daten abgeleiteten Messwerte sind für die Betriebsüberwachung und die Geschäftsüberwachung hilfreich. Mit Edge API Analytics können Sie beispielsweise ermitteln, welche APIs gut oder schlecht funktionieren, welche Entwickler den Traffic mit dem höchsten Wert liefern und welche Apps die meisten Probleme für Ihre Back-End-Dienste verursachen.
Für einen einfachen Zugriff auf diese Metrikdaten stellt Edge eine RESTful API bereit. Sie können die Metrics API verwenden, wenn Sie bestimmte Analytics-Funktionen automatisieren möchten, z. B. das regelmäßige Abrufen von Messwerten mit einem Automatisierungsclient oder -skript. Sie können die API auch verwenden, um Ihre eigenen Visualisierungen in Form von benutzerdefinierten Widgets zu erstellen, die Sie in Portale oder benutzerdefinierte Anwendungen einbetten können.
Informationen zur Verwendung von Analytics in der API Edge Management-Benutzeroberfläche finden Sie unter Übersicht über API Analytics.
Informationen zu den Messwert-APIs
Edge bietet zwei Messwert-APIs:
Die Get Metrics API gibt Messwerte für eine Organisation und Umgebung über einen bestimmten Zeitraum zurück, z. B. eine Stunde, einen Tag oder eine Woche.
Für die letzte Woche wollen Sie beispielsweise Folgendes abrufen:
- Anzahl der Richtlinienfehler
- Die durchschnittliche Antwortzeit
- Gesamter Traffic
Die Get Metrics Organized by Dimensions API gibt Messwerte für eine Organisation und eine Umgebung nach Dimension gruppiert über einen bestimmten Zeitraum zurück.
Für die letzte Woche beispielsweise verwenden Sie Dimensionen, um Messwerte nach API-Produkt, API-Proxy und Entwickler-E-Mail zu gruppieren und Folgendes zu erhalten:
- Die Anzahl der Richtlinienfehler pro API-Produkt
- Die durchschnittliche Antwortzeit pro API-Proxy
- Den gesamte Traffic pro Entwickler-E-Mail
Die API Nach Dimensionen geordnete Messwerte abrufen unterstützt zusätzliche Funktionen, die von der API Messwerte abrufen nicht unterstützt werden, darunter:
Informationen zu Metrics API-Kontingenten
Edge erzwingt die folgenden Kontingente für diese Aufrufe. Das Kontingent basiert auf dem Back-End-System, das den Aufruf verarbeitet:
- Postgres: 40 Aufrufe pro Minute
- BigQuery: 12 Aufrufe pro Minute
Bestimmen Sie das Back-End-System, das den Aufruf verarbeitet, indem Sie das Antwortobjekt untersuchen.
Jedes Antwortobjekt enthält ein metaData
-Attribut, das den Dienst auflistet, der den Aufruf im Source
-Attribut verarbeitet hat. Beispiel für Postgres:
{ ... "metaData": { "errors": [], "notices": [ "Source:Postgres", "Table used: xxxxxx.yyyyy", "query served by:111-222-333" ] } }
Für BigQuery ist das Attribut Source
:
"Source:Big Query"
Wenn Sie das Aufrufkontingent überschreiten, gibt die API den HTTP-Fehler 429 zurück.
Messwerte mit der Verwaltungs-API abrufen
Der Hauptunterschied zwischen den beiden APIs besteht darin, dass die Get Metrics API Rohmesswerte für die gesamte Organisation und Umgebung zurückgibt, während Sie über die Get Metrics Organised by Dimensions API Messwerte nach verschiedenen Entitätstypen gruppieren können, z. B. API-Produkt, Entwickler und App.
Die Anfrage-URL für die Get Metrics API lautet:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats
Für die Get Metrics Organised by Dimensions API fügen Sie der URL nach /stats
eine zusätzliche Ressource hinzu, die die gewünschte Dimension angibt:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension
Wenn Sie beispielsweise Messwerte nach API-Proxy gruppieren möchten, verwenden Sie die folgende URL, um die Verwaltungs-API aufzurufen:
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy
Messwerte angeben, die zurückgegeben werden sollen
Sowohl für die Get Metrics API als auch für die Get Metrics Organised by Dimensions API verwenden Sie den Abfrageparameter select
, um die abzurufenden metrics und eine optionale Aggregationsfunktion in folgendem Format anzugeben:
?select=metric
oder:
?select=aggFunction(metric)
Wobei:
- metric gibt die Daten an, die Sie zurückgeben möchten. Beispielsweise die Anzahl der API-Anfragen, Cache-Treffer oder Richtlinienfehler. Unter metrics finden Sie eine Tabelle, die den Namen des Messwerts angibt, der mit dem Abfrageparameter
select
verwendet werden soll. aggFunction gibt die optionale Aggregationsfunktion an, die für den Messwert ausgeführt wird. Beispielsweise können Sie die folgenden Aggregationsfunktionen mit dem Messwert für die Verarbeitungslatenz verwenden:
avg
: Gibt die durchschnittliche Verarbeitungslatenz zurück.min
: Gibt die minimale Verarbeitungslatenz zurück.max
: Gibt die maximale Verarbeitungslatenz zurück.-
sum
: Gibt die Summe aller Verarbeitungslatenzen zurück.
Nicht alle Messwerte unterstützen alle Aggregationsfunktionen. Die Dokumentation zu metrics enthält eine Tabelle, die den Namen des Messwerts und die Funktion (
sum
,avg
,min
,max
) unterstützt durch den Messwert enthält.
So können Sie beispielsweise die durchschnittliche Anzahl der Transaktionen, d. h. API-Proxy-Anfragen, pro Sekunde zurückgeben:
?select=tps
Beachten Sie, dass für dieses Beispiel keine Aggregationsfunktion erforderlich ist. Das nächste Beispiel verwendet eine Aggregationsfunktion, um die Summe der Cache-Treffer zurückzugeben:
?select=sum(cache_hit)
Sie können mehrere Messwerte für einen einzelnen API-Aufruf zurückgeben. Wenn Sie Messwerte für die Summe der Richtlinienfehler und der durchschnittlichen Anfragegröße abrufen möchten, geben Sie für den Abfrageparameter select
eine durch Kommas getrennte Liste von Messwerten an:
?select=sum(policy_error),avg(request_size)
Zeitraum angeben
Die Metrics API gibt Daten für einen bestimmten Zeitraum zurück. Verwenden Sie den Abfrageparameter timeRange
, um den Zeitraum in folgendem Format anzugeben:
?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM
Beachten Sie die Angabe %20
vor HH:MM
. Der Parameter timeRange
erfordert ein URL-codiertes Leerzeichen vor HH:MM
oder ein +
-Zeichen wie in MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM
.
Beispiel:
?timeRange=03/01/2018%2000:00~03/30/2018%2023:59
Verwenden Sie 24:00 nicht als Uhrzeit, da es zu 00:00 Uhr geändert wird. Verwenden Sie stattdessen 23:59.
Verwendung eines Trennzeichens
Wenn Sie mehrere Dimensionen in einem API-Aufruf trennen möchten, verwenden Sie ein Komma (,
) als Trennzeichen.
Im API-Aufruf
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
werden die Dimensionen apis
und apps
durch ,
getrennt.
Beispiele für API-Aufrufe
Dieser Abschnitt enthält Beispiele für die Verwendung der Get Metrics API und der Get Metrics Organised by Dimensions API. Weitere Beispiele finden Sie unter Beispiele für Messwert-API.
Gibt die Gesamtzahl der Aufrufe an Ihre APIs für 1 Monat zurück.
Verwenden Sie die Get Metrics API, um die Gesamtzahl der Aufrufe aller APIs in Ihrer Organisation und Umgebung für einen Monat anzuzeigen:
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
Beispielantwort:
{ "environments": [ { "metrics": [ { "name": "sum(message_count)", "values": [ "7.44944088E8" ] } ], "name": "prod" } ], ... }
Die Gesamtzahl der Nachrichten pro API-Proxy für 2 Tage zurückgeben
In diesem Beispiel geben Sie Messwerte für die Anzahl der Anfragen zurück, die von einem API-Proxy über einen Zeitraum von zwei Tagen empfangen wurden. Mit dem Abfrageparameter select
wird die Aggregatfunktion sum
für den Messwert message_count
in der Dimension apiproxy
definiert. Der Bericht gibt den Durchsatz der Anfragenachrichten für alle APIs zurück, die zwischen dem 20.06.2018 und dem 21.06.2018 in UTC-Zeit empfangen wurden:
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
Beispielantwort:
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(message_count)", "values" : [ { "timestamp" : 1498003200000, "value" : "1100.0" } ] } ], "name" : "target-reroute" } ], "name" : "test" } ]... }
Diese Antwort gibt an, dass 1.100 Nachrichten von einem API-Proxy mit dem Namen "target-reroute" empfangen wurden, der in der Testumgebung zwischen dem 20.06.2018 und dem 21.6.2018 ausgeführt wurde.
Um Messwerte für andere Dimensionen abzurufen, geben Sie als URI-Parameter eine andere Dimension an. Sie können beispielsweise die Dimension developer_app
angeben, um Messwerte für Entwickleranwendungen abzurufen. Der folgende API-Aufruf gibt den Gesamtdurchsatz (empfangene Nachrichten) aller Anwendungen für das angegebene Zeitintervall zurück:
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
Beispielantwort:
{ "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" } ]... }
Ergebnisse nach relativer Rangfolge sortieren
Beim Abrufen von Messwerten möchten Sie oft nur Ergebnisse für eine Teilmenge der gesamten Datenmenge erhalten. Normalerweise brauchen Sie die Ergebnisse für die „Top 10“, z. B. die „10 langsamsten APIs“, die „10 aktivsten Anwendungen“. Dazu können Sie den Abfrageparameter topk
als Teil der Anfrage verwenden.
So können Sie beispielsweise herausfinden, wer Ihre Top-Entwickler sind, gemessen am Durchsatz, oder welche Ziel APIs nach Latenz am wenigsten leistungsstark sind (z. B. "höchste/niedrigste Leistung").
Die topk
(d. h. "Top-K"-Entitäten) ermöglicht die Berichterstellung für die Entitäten, die dem höchsten Wert für einen bestimmten Messwert zugeordnet sind. Auf diese Weise können Sie Messwerte nach einer Liste von Entitäten filtern, die eine bestimmte Bedingung veranschaulichen. Um beispielsweise herauszufinden, welche Ziel-URL in der letzten Woche am fehleranfälligsten war, wird der Parameter topk
mit dem Wert 1
an die Anfrage angehängt:
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" } ]... }
Das Ergebnis dieser Anfrage sind verschiedene Messwerte, aus denen hervorgeht, dass die fehlerhafteste Ziel-URL http://api.company.com
ist.
Sie können auch den Parameter topk
verwenden, um nach den APIs zu sortieren, die den höchsten Durchsatz haben. Im folgenden Beispiel werden Messwerte aus der API mit dem höchsten Ranking abgerufen, die durch den höchsten Durchsatz der letzten Woche definiert wurde:
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
Beispielantwort:
{ "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" } ]... }
Ergebnisse filtern
Für eine größere Detaillierungsgrad können Sie die Ergebnisse filtern, um die zurückgegebenen Daten zu begrenzen. Wenn Sie Filter verwenden, müssen Sie Dimensionen als Filterattribute verwenden.
Angenommen, Sie müssen die Anzahl der Fehler von Back-End-Diensten abrufen, die vom HTTP-Verb der Anfrage gefiltert werden. Ihr Ziel ist es herauszufinden, wie viele POST- und PUT-Anfragen Fehler pro Backend-Dienst erzeugen. Dazu verwenden Sie die Dimension target_url
zusammen mit dem Filter 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
Beispielantwort:
{ "environments" : [ { "dimensions" : [ { "metrics" : [ { "name" : "sum(is_error)", "values" : [ { "timestamp" : 1519516800000, "value" : "1.0" } ] } ], "name" : "testCache" } ], "name" : "test" } ]... }
Paginierungsergebnisse
In Produktionsumgebungen geben einige Anfragen an die Edge Analytics API sehr große Datasets zurück. Um die Anzeige großer Datensets im Kontext einer UI-basierten Anwendung zu vereinfachen, unterstützt die API nativ die Paginierung.
Um für die Ergebnisse Seitenumbruch zu machen, verwenden Sie die Abfrageparameter offset
und limit
zusammen mit dem Sortierparameter sortby
, um eine konsistente Reihenfolge der Elemente sicherzustellen.
Die folgende Anfrage würde zum Beispiel wahrscheinlich ein großes Dataset zurückgeben, da sie Messwerte für alle Fehler in allen APIs in der Produktumgebung der letzten Woche abruft.
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
Wenn Ihre UI-basierte Anwendung 50 Ergebnisse pro Seite anzeigen kann, können Sie den Grenzwert auf 50 festlegen. Da 0 als erstes Element zählt, gibt der folgende Aufruf die Elemente 0-49 in absteigender Reihenfolge zurück (sort=DESC
ist die Standardeinstellung).
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
Für die zweite „Seite“ der Ergebnisse verwenden Sie so den Offset-Abfrageparameter. Beachten Sie, dass der Grenzwert und der Offset identisch sind. Das liegt daran, dass 0 als erstes Element zählt. Bei einem Limit von 50 und einem Offset von 0 werden die Elemente 0-49 zurückgegeben. Mit einem Offset von 50 werden die Artikel 50-99 zurückgegeben.
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