Metrik-APIs verwenden

Sie sehen die Dokumentation zu Apigee Edge.
Zur Dokumentation zuApigee X wechseln. info

Apigee Edge zeichnet eine Vielzahl von Betriebs- und Geschäftsdaten auf, die über APIs übertragen werden. Die aus diesen Daten abgeleiteten Messwerte sind hilfreich für das Betriebs-Monitoring und das Geschäfts-Monitoring. Mit Edge API Analytics können Sie beispielsweise ermitteln, welche APIs gut oder schlecht funktionieren, welche Entwickler den Traffic mit der höchsten Wertschöpfung bringen und welche Anwendungen die meisten Probleme für Ihre Backend-Dienste verursachen.

Um den Zugriff auf diese Messdaten zu erleichtern, stellt Edge eine RESTful API zur Verfügung. Sie können die Messwert-API verwenden, wenn Sie bestimmte Analysefunktionen automatisieren möchten, z. B. das regelmäßige Abrufen von Messwerten mithilfe eines Automatisierungsclients oder -skripts. 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-Verwaltungs-UI finden Sie unter API Analytics – Übersicht.

Informationen zu den Messwert-APIs

Edge bietet zwei Messwert-APIs:

• Get metrics 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
  • Durchschnittliche Antwortzeit
  • Gesamter Traffic

• Die Get Metrics Organized by Dimensions API gibt Messwerte für eine Organisation und eine Umgebung nach Dimension ü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 Get Metrics Organised by Dimensions API unterstützt zusätzliche Features, die von der Get Metrics API nicht unterstützt werden, einschließlich:

  • Sortieren
  • Filtern
  • Paginieren

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. Untersuchen Sie dazu das Antwortobjekt. 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 sieht das Source-Attribut so aus:

"Source:Big Query"

Wenn Sie das Aufrufkontingent überschreiten, gibt die API den HTTP-Fehler 429 zurück.

Messwerte mit der Management API abrufen

Der Hauptunterschied zwischen den beiden APIs besteht darin, dass Get metrics Rohmesswerte für die gesamte Organisation und Umgebung zurückgibt, während Get metrics organized by dimensions Sie 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 Management 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 select Abfrageparameter, um die Messdaten anzugeben, die abgerufen werden sollen, sowie eine optionale Aggregationsfunktion in folgendem Format:

?select=metric

oder:

?select=aggFunction(metric)

Wobei:

• `metric` legt die Daten fest, die Sie zurückgeben möchten. Beispielsweise die Anzahl der API-Anfragen, Cache-Treffer oder Richtlinienfehler. Unter Messwerte 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 Messwerten enthält eine Tabelle, die den Namen des Messwerts und die Funktion (sum, avg, min, max) unterstützt durch den Messwert enthält.

Um beispielsweise die durchschnittliche Anzahl von Transaktionen, also API-Proxy-Anfragen, pro Sekunde zurückzugeben:

?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 timeRange Abfrageparameter, 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.

Trennzeichen verwenden

Verwenden Sie ein Komma (,) als Trennzeichen, um mehrere Dimensionen in einem API-Aufruf zu trennen. Beispiel: 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 und der Get Metrics Organised by Dimensions APIs. Weitere Beispiele finden Sie unter Beispiele für Messwert-API.

Die Gesamtzahl der Aufrufe an Ihre APIs für 1 Monat zurückgeben

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 für eine 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 topk Parameter mit einem Wert von 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 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.

Nehmen wir beispielsweise an, Sie müssen eine Anzahl von Fehlern von Backend-Diensten abrufen, die nach dem HTTP-Verb der Anfrage gefiltert sind. 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 Data sets zurück. Um die Anzeige großer Datasets 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 offset und limit Abfrageparameter, zusammen mit dem sortby Sortierparameter, 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