Metrik-APIs verwenden

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