Asynchrone API für benutzerdefinierte Berichte verwenden

Sie sehen die Dokumentation zu Apigee Edge.
Zur Apigee X-Dokumentation weitere Informationen

Edge Analytics bietet zahlreiche interaktive Dashboards, benutzerdefinierte Berichtsgeneratoren und verwandte Funktionen. Diese Funktionen sind jedoch für die Interaktion gedacht: Sie senden entweder eine API- oder UI-Anfrage, und die Anfrage wird blockiert, bis der Analyseserver eine Antwort sendet.

Bei Analytics-Anfragen kann es jedoch zu einer Zeitüberschreitung kommen, wenn deren Verarbeitung zu lange dauert. Wenn eine Abfrageanfrage eine große Datenmenge verarbeiten muss (z. B. Hunderte von GB), schlägt sie möglicherweise aufgrund einer Zeitüberschreitung fehl.

Bei der asynchronen Abfrageverarbeitung können Sie sehr große Datasets abfragen und die Ergebnisse zu einem späteren Zeitpunkt abrufen. Sie könnten eine Offline-Abfrage in Betracht ziehen, wenn Sie feststellen, dass bei Ihren interaktiven Abfragen eine Zeitüberschreitung auftritt. Einige Situationen, in denen die asynchrone Abfrageverarbeitung eine gute Alternative darstellt, sind:

• Analysieren und Erstellen von Berichten, die große Zeitintervalle umfassen.
• Analysieren von Daten mit einer Vielzahl von Gruppierungsdimensionen und anderen Einschränkungen, die die Abfrage komplexer machen
• Verwalten von Abfragen, wenn Sie feststellen, dass die Datenmengen für einige Nutzer oder Organisationen erheblich gestiegen sind.

In diesem Dokument wird beschrieben, wie asynchrone Anfragen mithilfe der API initiiert werden. Sie können auch die UI verwenden, wie unter Benutzerdefinierten Bericht ausführen beschrieben.

Reports API mit der Benutzeroberfläche vergleichen

Benutzerdefinierte Berichte erstellen und verwalten beschreibt, wie Sie mit der Edge-Benutzeroberfläche benutzerdefinierte Berichte erstellen und ausführen. Sie können diese Berichte synchron oder asynchron ausführen.

Die meisten Konzepte zum Erstellen benutzerdefinierter Berichte mit der Benutzeroberfläche gelten für die Verwendung der API. Geben Sie also beim Erstellen von benutzerdefinierten Berichten mit der API die in Edge integrierten metrics, Dimensionen und Filter sowie alle benutzerdefinierten Messwerte an, die Sie mithilfe der StatisticsCollector-Richtlinie erstellt haben.

Die Hauptunterschiede zwischen den in der Benutzeroberfläche und der API generierten Berichten bestehen darin, dass mit der API erstellte Berichte in CSV- oder JSON-Dateien (durch Zeilenumbruch getrennt) geschrieben werden und nicht in einen visuellen Bericht, der auf der Benutzeroberfläche angezeigt wird.

Limits in Apigee Hybrid

Apigee Hybrid erzwingt eine Größenbeschränkung von 30 MB für den Ergebnisdatensatz.

So erstellen Sie eine asynchrone Analyseabfrage

Sie führen asynchrone Analyseabfragen in drei Schritten aus:

1. Abfrage senden.

2. Abfragestatus abrufen.

3. Abfrageergebnisse abrufen.

Schritt 1: Abfrage senden

Sie müssen eine POST-Anfrage an die /queries API senden. Diese API weist Edge an, Ihre Anfrage im Hintergrund zu verarbeiten. Wenn die Übermittlung der Abfrage erfolgreich war, gibt die API den Status 201 und eine ID zurück, mit der Sie in späteren Schritten auf die Abfrage verweisen.

Beispiel:

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries -d @json-query-file
-u orgAdminEmail:password

Der Anfragetext ist eine JSON-Beschreibung der Abfrage. Geben Sie im JSON-Text die metrics, Dimensionen und Filter an, die den Bericht definieren.

Hier sehen Sie eine Beispieldatei für json-query-file:

{ 
   "metrics":  [
     {
         "name": "message_count",
         "function": "sum",
         "alias": "sum_txn"
    }
        ],
    "dimensions": ["apiproxy"],
    "timeRange": "last24hours",
    "limit": 14400,
    "filter":"(message_count ge 0)"         
}

Eine vollständige Beschreibung der Syntax des Anfragetexts finden Sie unter Informationen zum Anfragetext.

Beispielantwort:

Beachten Sie, dass die Abfrage-ID 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd in der Antwort enthalten ist. Neben dem HTTP-Status 201 bedeutet der state von enqueued, dass die Anfrage erfolgreich war.

HTTP/1.1 201 Created

{  
  "self":"/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
  "created":"2018-05-10T07:11:10Z",
  "state":"enqueued",
  "error":"false",
}

Schritt 2: Abfragestatus abrufen

Führen Sie einen GET-Aufruf aus, um den Status der Abfrage anzufordern. Sie geben die Abfrage-ID an, die vom POST-Aufruf zurückgegeben wurde. Beispiel:

curl -X GET -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd
-u email:password

Beispielantworten:

Wenn die Abfrage noch in Bearbeitung ist, erhalten Sie eine Antwort wie die folgende, wobei state running ist:

{
    "self": "/organizations/myorg/environments/myenv/queries/1577884c-4f48-4735-9728-5da4b05876ab",
    "state": "running",
    "created": "2018-02-23T14:07:27Z",
    "updated": "2018-02-23T14:07:54Z"
}

Nachdem die Abfrage erfolgreich abgeschlossen wurde, wird eine Antwort wie die folgende angezeigt, wobei state auf completed gesetzt ist:

{
      "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd",
      "state": "completed",
      "result": {
        "self": "/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result",
        "expires": "2017-05-22T14:56:31Z"
      },
      "resultRows": 1,
      "resultFileSize": "922KB",
      "executionTime": "11 sec",
      "created": "2018-05-10T07:11:10Z",
      "updated": "2018-05-10T07:13:22Z"
}

Schritt 3: Abfrageergebnisse abrufen

Sobald der Abfragestatus completed lautet, können Sie die get results API verwenden, um die Ergebnisse abzurufen. Dabei lautet die Abfrage-ID wieder 9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.

curl -X GET -H "Content-Type:application/json" -O -J https://api.enterprise.apigee.com/v1/organizations/myorg/environments/myenv/queries/9cfc0d85-0f30-46d6-ae6f-318d0cb961bd/result
-u email:password

Zum Abrufen der heruntergeladenen Datei müssen Sie das von Ihnen verwendete Tool so konfigurieren, dass eine heruntergeladene Datei auf Ihrem System gespeichert wird. Beispiel:

• Wenn Sie cURL verwenden, können Sie die Optionen -O -J wie oben gezeigt verwenden.

• Wenn Sie Postman verwenden, müssen Sie die Schaltfläche Speichern und herunterladen anklicken. In diesem Fall wird eine ZIP-Datei mit dem Namen response heruntergeladen.

• Wenn Sie den Chrome-Browser verwenden, wird der Download automatisch akzeptiert.

Wenn die Anfrage erfolgreich ist und die Ergebnismenge ungleich null ist, wird das Ergebnis als gezippte JSON-Datei (durch Zeilenumbruch getrennt) an den Client heruntergeladen. Der Name der heruntergeladenen Datei lautet:

OfflineQueryResult-<query-id>.zip

Beispiel:

OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip

Die ZIP-Datei enthält eine .gz-Archivdatei der JSON-Ergebnisse. Entpacken Sie die Download-Datei und extrahieren Sie die JSON-Datei mit dem Befehl gzip, um auf die JSON-Datei zuzugreifen:

unzip OfflineQueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd.zip
gzip -d QueryResult-9cfc0d85-0f30-46d6-ae6f-318d0cb961bd-000000000000.json.gz

Informationen zum Anfragetext

In diesem Abschnitt werden alle Parameter beschrieben, die Sie im JSON-Anfragetext für eine Abfrage verwenden können. Weitere Informationen zu Messwerten und Dimensionen, die Sie in Ihrer Abfrage verwenden können, finden Sie in der Referenz zu Analytics.

{  
   "metrics":[  
      {  
        "name":"metric_name",
        "function":"aggregation_function",
        "alias":"metric_dispaly_name_in_results",
        "operator":"post_processing_operator",
        "value":"post_processing_operand"
      },
   ...
   ],
   "dimensions":[  
      "dimension_name",
      ...
   ],
   "timeRange":"time_range",
   "limit":results_limit,
   "filter":"filter",
   "groupByTimeUnit": "grouping",
   "outputFormat": "format",
   "csvDelimiter": "delimiter"
}

"metrics":[  
  {  
    "name":"response_processing_latency",
    "function":"avg",
    "alias":"average_response_time_in_seconds",
    "operator":"/",
    "value":"1000"
  }
]

"timeRange": {
    "start": "2018-07-29T00:13:00Z",
    "end": "2018-08-01T00:18:00Z"
}

Filterausdruckssyntax

In diesem Referenzabschnitt werden die Tokens beschrieben, mit denen Sie Filterausdrücke im Anfragetext erstellen können. Der folgende Ausdruck verwendet beispielsweise das Token „ge“ (größer oder gleich):

"filter":"(message_count ge 0)"

(apiproxy in 'ethorapi','weather-api')

(apiproxy in 'ethorapi')

(apiproxy in 'Search','ViewItem')

(response_status_code in 400,401,500,501)

(response_status_code notin 400,401,500,501)

(response_status_code eq 504)

(apiproxy eq 'non-prod')

(response_status_code ne 500)

(apiproxy ne 'non-prod')

(response_status_code gt 500)

(response_status_code lt 500)

(target_response_code ge 400)

(target_response_code le 300)

(apiproxy like '%buy%')

(apiproxy like '%item')

(apiproxy like 'Prod%')

(apiproxy not like '%buy%')

(apiproxy not like '%item')

(apiproxy not like 'Prod%')

(target_response_code gt 399) and (response_status_code ge 400)

(response_size ge 1000) or (response_status_code eq 500)

Einschränkungen und Standardwerte

Im Folgenden finden Sie eine Liste mit Einschränkungen und Standardeinstellungen für die asynchrone Abfrageverarbeitungsfunktion.

Informationen zu Abfrageergebnissen

Das folgende Beispiel zeigt ein Ergebnis im JSON-Format. Die Ausgabe besteht aus JSON-Zeilen, die durch einen Zeilenumbruch getrennt sind.

{"message_count":"10209","apiproxy":"guest-auth-v3","hour":"2018-08-07 19:26:00 UTC"}
{"message_count":"2462","apiproxy":"carts-v2","hour":"2018-08-06 13:16:00 UTC"}    
…

Sie können die Ergebnisse von der URL abrufen, bis die Daten im Repository abgelaufen sind. Weitere Informationen finden Sie unter Einschränkungen und Standardwerte.

Beispiele

Beispiel 1: Summe der Nachrichtenanzahl

Abfrage der Summe der Nachrichtenanzahl in den letzten 60 Minuten.

Abfrage

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Anfragetext von last60minutes.json anfordern

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":"last60minutes"
}

Beispiel 2: Benutzerdefinierter Zeitraum

Abfrage mit einem benutzerdefinierten Zeitraum.

Abfrage

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1 /organizations/myorg/environments/test/queries"
-d @last60minutes.json
-u orgAdminEmail:password

Anfragetext von last60minutes.json anfordern

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Beispiel 3: Transaktionen pro Minute

Abfrage des Messwerts für Transaktionen pro Minute (tpm).

Abfrage

curl -X POST -H "Content-Type: application/json" -H "Accept: application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @tpm.json
-u orgAdminEmail:password

Anfragetext von tpm.json

{  
   "metrics":[  
      {  
         "name":"tpm"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-07-01T11:00:00Z",
      "end":"2018-07-30T11:00:00Z"
   }
}

Beispielergebnis

Auszug aus der Ergebnisdatei:

{"tpm":149995.0,"apiproxy":"proxy_1","minute":"2018-07-06 12:16:00 UTC"}
{"tpm":149998.0,"apiproxy":"proxy_1","minute":"2018-07-09 15:12:00 UTC"}
{"tpm":3.0,"apiproxy":"proxy_2","minute":"2018-07-11 16:18:00 UTC"}
{"tpm":148916.0,"apiproxy":"proxy_1","minute":"2018-07-15 17:14:00 UTC"}
{"tpm":150002.0,"apiproxy":"proxy_1","minute":"2018-07-18 18:11:00 UTC"}
...

Beispiel 4: Filterausdruck verwenden

Abfrage mit einem Filterausdruck, der einen booleschen Operator verwendet.

Abfrage

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries"
-d @filterCombo.json
-u orgAdminEmail:password

Anfragetext von filterCombo.json

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum"
      },
      {  
         "name":"total_response_time",
         "function":"avg",
         "alias":"average_response_time"
      }
   ],
   "filter":"(apiproxy ne \u0027proxy_1\u0027) and (apiproxy ne \u0027proxy_2\u0027)",
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":1000,
   "timeRange":{  
      "start":"2018-11-01T11:00:00Z",
      "end":"2018-11-30T11:00:00Z"
   }
}

Beispiel 5: Übergabe des Ausdrucks im Messwertparameter

Abfrage mit einem Ausdruck, der als Teil des Messwerts übergeben wird. Sie können nur einfache Ein-Operator-Ausdrücke verwenden.

Abfrage

curl -X POST -H "Content-Type:application/json"
https://api.enterprise.apigee.com/v1/organizations/myorg/environments/test/queries" 
-d @metricsExpression.json
-u orgAdminEmail:password

Anfragetext von metricsExpression.json anfordern

{  
   "metrics":[  
      {  
         "name":"message_count",
         "function":"sum",
         "operator":"/",
         "value":"7"
      }
   ],
   "dimensions":[  
      "apiproxy"
   ],
   "groupByTimeUnit":"minute",
   "limit":10,
   "timeRange":"last60minutes"
}

So erstellen Sie eine asynchrone Monetarisierungsberichtsabfrage

Mit den in diesem Abschnitt beschriebenen Schritten kannst du alle erfolgreichen Monetarisierungstransaktionen innerhalb eines bestimmten Zeitraums nach bestimmten Kriterien erfassen.

Wie bei asynchronen Analyseabfragen führen Sie asynchrone Monetarisierungsberichtsabfragen in drei Schritten durch: (1) Senden Sie die Abfrage, (2) rufen Sie den Abfragestatus ab und (3) rufen Sie die Abfrageergebnisse ab.

Schritt 1, Senden der Abfrage, wird unten beschrieben.

Die Schritte 2 und 3 sind identisch mit denen für asynchrone Analyseabfragen. Weitere Informationen finden Sie unter So machen Sie eine asynchrone Analyseabfrage.

Um eine Abfrage für einen asynchronen Monetarisierungsbericht zu senden, senden Sie eine POST-Anfrage an /mint/organizations/org_id/async-reports.

Optional können Sie die Umgebung angeben, indem Sie den Abfrageparameter environment übergeben. Wenn keine Angabe erfolgt, wird standardmäßig der Abfrageparameter prod verwendet. Beispiel:

/mint/organizations/org_id/async-reports?environment=prod

Geben Sie im Anfragetext die folgenden Suchkriterien an.

"devCriteria":[{
    "id":"RtHAeZ6LtkSbEH56",
    "orgId":"my_org"}
]

Die folgende Anfrage generiert beispielsweise einen asynchronen Monetarisierungsbericht für den Monat Juni 2017 für das angegebene API-Produkt und die Entwickler-ID. Die Daten und Uhrzeiten für fromDate und toDate in Berichten sind in UTC/GMT angegeben und können Uhrzeiten enthalten.

curl -H "Content-Type:application/json" -X POST -d \
'{
      "fromDate":"2017-06-01 00:00:00",
      "toDate":"2017-06-30 00:00:00",    
     "productIds": [
        "a_product"
    ],
    "devCriteria": [{
        "id": "AbstTzpnZZMEDwjc",
        "orgId": "myorg"
    }]

 }' \
"https://api.enterprise.apigee.com/v1/mint/organizations/myorg/async-reports?environment=prod" \
-u orgAdminEmail:password