Metrics API verwenden

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Apigee 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 Apigee Analytics können Sie beispielsweise ermitteln, welche APIs gut oder schlecht funktionieren, welche Entwickler den höchsten Traffic liefern und welche Anwendungen die meisten Probleme für Ihre Backend-Dienste verursachen.

Verwenden Sie die Messwert-API, um auf einfache Weise auf diese Messdaten zuzugreifen, 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 Apigee-Benutzeroberfläche finden Sie in der Apigee Analyse-Übersicht.

Informationen zur Metrics API

Sie können die Metrics API auf zwei Arten verwenden:

  • Erhalten Sie Messdaten für eine Organisation und Umgebung über einen bestimmten Zeitraum, z. B. 1 Stunde, 1 Tag oder 1 Woche. Diese Methode gibt unverarbeitete Messwerte für die gesamte Organisation und Umgebung zurück.

    Für die letzte Woche wollen Sie beispielsweise Folgendes abrufen:

    • Anzahl der Richtlinienfehler
    • Durchschnittliche Antwortzeit
    • Zugriffe insgesamt

  • Sie können Messwerte nach Dimension organisiert über einen bestimmten Zeitraum für eine Organisation und Umgebung abrufen.

    Für die letzte Woche können Sie Dimensionen beispielsweise verwenden, um Messwerte nach API-Produkt, API-Proxy und Entwickler-E-Mail (die auch eine AppGroup-ID sein kann) zu gruppieren, um Folgendes abzurufen:

    • Die Anzahl der Richtlinienfehler pro API-Produkt
    • Durchschnittliche Antwortzeit pro API-Proxy
    • Gesamter Traffic pro Entwickler-E-Mail

    Zur Verwaltung des zurückgegebenen Ergebnisses unterstützt die Metrics API die folgenden Funktionen:

    Weitere Informationen finden Sie in der Referenz zur Metrics API.

    Erste Schritte mit der Metrics API

    Die Anfrage-URL für die Metrics-API lautet:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    Wenn Sie beispielsweise Messwerte abrufen möchten, die nach API-Proxy gruppiert, verwenden Sie die folgende URL, um die Apigee API aufzurufen:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

    Lassen Sie die Dimension weg, um Rohmesswerte für die gesamte Organisation und Umgebung für den angegebenen Zeitraum zurückzugeben:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    Messwerte angeben, die zurückgegeben werden sollen

    Verwenden Sie den Abfrageparameter select, um die abzurufenden Messwerte und eine optionale Aggregationsfunktion im folgenden Format anzugeben:

    ?select=metric

    oder:

    ?select=aggFunction(metric)

    Dabei gilt:

    • 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.
      • p50: Gibt das 50. Perzentil für die Verarbeitungslatenz zurück.
      • p95: Gibt das 95. Perzentil für die Verarbeitungslatenz zurück.
      • p99: Gibt das 99. Perzentil für die Verarbeitungslatenz 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 Abfrageparameter timeRange (max. 6 Monate), 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.

    Beispiele für den Aufruf der Metrics API

    Dieser Abschnitt enthält Beispiele zur Verwendung der Metrics-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.

    Wenn Sie die Gesamtzahl der Aufrufe für alle APIs in Ihrer Organisation und Umgebung für 1 Monat zurückgeben möchten, verwenden Sie einen Aufruf ähnlich dem folgenden:

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen findet sich unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen findet sich unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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 Parameter topk mit einem Wert von 1 an die Anfrage angehängt:

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen findet sich unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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')" \
  -H "Authorization: Bearer $TOKEN"

    Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen findet sich unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

    Im Folgenden finden Sie ein Beispiel für die Antwort:

    {
  "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 Apigee 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    Dabei ist $TOKEN auf Ihr OAuth 2.0-Zugriffstoken festgelegt. Weitere Informationen hierzu finden Sie unter OAuth 2.0-Zugriffstoken abrufen. Informationen zu den in diesem Beispiel verwendeten curl-Optionen finden Sie unter curl verwenden. Eine Beschreibung der verwendeten Umgebungsvariablen findet sich unter Umgebungsvariablen für Apigee API-Anfragen festlegen.

    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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"