Verwenden des Ereignis-Scrollvorgangs zum Exportieren von Analysedaten

Online bearbeiten

Verwenden Sie die/events/scroll Vorgang zum Exportieren von 10.000 oder mehr Analyseereignisdatensätzen mit der REST-API.

Die Standardmethode zum Abrufen von Analytics-Ereignisdaten über die API Connect Analytics-REST-API ist die Verwendung des /events API-Aufrufs. Der/events Der API-Aufruf ist für den schnellen Abruf der aktuellsten Ereignisdaten optimiert und auf die Rückgabe von maximal 10.000 API-Ereignisdatensätzen beschränkt. Wenn Sie mehr als 10.000 Ereignisdatensätze abrufen möchten, verwenden Sie die/events/scroll API, die für den Abruf großer Mengen analytischer Ereignisdaten optimiert ist.

Wenn Sie Ihre Analysedaten abfragen mit/events/scroll , OpenSearch findet alle Ereignisdatensätze, die Ihrer Abfrage entsprechen, und erstellt einen Zeiger, der als Bildlaufkontext bezeichnet wird. Anschließend verwenden Sie den Bildlaufkontext, um die Ereignisdaten stapelweise abzurufen.

Wichtig: Die Erstellung der Ergebnismenge und des Scroll-Kontexts erfordert viel OpenSearch Ressourcen. Es wird empfohlen, nicht mehrere verschiedene/events/scroll Abfragen gleichzeitig auszuführen und den Scroll-Kontext zu löschen, nachdem Ihre Ereignisdaten abgerufen wurden.

Exportieren von Analyseereignissen mit/events/scroll

Der/events/scroll Der Vorgang gibt Ereignisdaten stapelweise zurück. Sie definieren die Batchgröße beim ersten Aufruf von/events/scroll , und rufen Sie dann jeden Stapel in nachfolgenden Aufrufen ab. Jeder weitere Anruf muss an/events/scroll innerhalb einer bestimmten Zeit, die als Keep-Alive-Zeit des Scroll-Kontexts bezeichnet wird. Das Verfahren ist wie folgt:

  1. Machen Sie den ersten/events/scroll Anruf. Geben Sie die Batchgröße und die Keep-Alive-Zeit für den Scroll-Vorgang an. Um beispielsweise Ereignisdaten in Batches von 1000 zurückzugeben und den Scroll-Kontext 10 Minuten lang aktiv zu halten, senden Sie den folgenden JSON-Code per POST an/events/scroll :
    {
  "size": 1000, # Return the first 1000 event records.
  "scroll": 10m # Keep the scroll context alive for 10 minutes.
}
    • sizedefiniert die Batchgröße.
    • scrolldefiniert die Keep-Alive-Zeit und verwendet das Format <Zahl><Einheiten>, Zum Beispiel: 30s, 5m, 3h, 1d. Der Maximalwert fürscroll Ist 1d.
    Draft comment: iainsoed@uk.ibm.com
    technote says: "Scroll contexts will stay alive for 10 minutes by default " and "Due to an OpenSearch limitation, if the scroll parameter is not included on subsequent requests with scroll_id, no scroll ID will be returned."

    For this reason, simplest just to tell user to always specify it, and don't rely on the default for the first call.

    Beispielantwort:
    {
    "total": 5926, # The total events found that match the query.
    "scroll_id": "FGl....", # Scroll context id to be used to get the next batch.
    "events": [...] # First batch of event data.
}
  2. Machen Sie den nächsten/events/scroll Anruf unter Angabe derscroll_id aus der vorherigen Antwort:
    {
  "size": 1000,
  "scroll_id": "<as returned from previous call>",
  "scroll": 10m 
}
    Die API gibt den nächsten Batch von 1000 Ereignisdatensätzen zurück und einen neuenscroll_id für den nächsten Anruf.
    Notiz: Wenn deinscroll_id abgelaufen ist, wird die folgende Antwort zurückgegeben:
    {
  "status": 404,
  "message": [
    {
      "trace": "7c7b3b11ee0e95b61452e8a78086d8e2",
      "errors": [
        {
          "code": "search_context_missing_exception",
          "message": "No search context found for id [48420]",
          "more_info": ""
        }
      ]
    }
  ]
}

    Wenn deinscroll_id abläuft, müssen Sie von vorne beginnen. Stellen Sie eine höhere Keep-Alive-Zeit für den Scroll-Kontext ein, um mehr Zeit für die Rückgabe von Ereignisdatensatz-Batches und den nächsten/events/scroll Anruf getätigt werden.

  3. Machen Sie weiter/events/scroll Anrufe, Aktualisierung derscroll_id jedes Mal mit der Antwort vom vorherigen Anruf.
  4. Nach dem letzten Aufruf zum Abrufen Ihrer Ereignisdaten löschen Sie den Scroll-Kontext mit einem POST an/events/scroll/delete :
    {"scroll_id": "<as returned from previous call>"}
    Beispielantwort:
    {
    "succeeded": true,
    "num_freed": 15
}
    Notiz: Der Scroll-Kontext wird automatisch gelöscht, wenn er abläuft. Wenn Sie jedoch über eine lange Keep-Alive-Zeit verfügen, wird empfohlen, ihn explizit zu löschen, um Ressourcen freizugeben.

Ausgearbeitetes Beispiel

Das folgende Beispiel zeigt, wie Sie dencurl zum manuellen Abrufen Ihrer API-Ereignisdaten mithilfe des Befehls/events/scroll API.
Notiz: Bei großen Mengen von Analysedaten ist der manuelle Abruf mitcurl ist langsam und anfällig für menschliche Fehler. Ein besserer Ansatz besteht darin, ein Skript zu schreiben, um die/events/scroll Anrufe und aktualisieren Sie diescroll_id bei jedem Anruf. Ein Beispiel für ein „ Python “-Skript finden Sie unter https://ibm.biz/apic-analytics-events-scroll.
  1. Ermitteln Sie die Gesamtzahl der Ereignisdatensätze, um die optimale Batchgröße und die Anzahl der durchzuführenden Anrufe zu ermitteln:
    curl -k -X GET --url 'https://example.api.connect.com/analytics/analytics/cloud/events/count' -H 'Authorization: Bearer <bearer_token>'
    {
    "total": 12453
}

    Bei 12.453 Ereignissen kann eine Batchgröße von 1.250 und insgesamt 10 Aufrufe ein guter Kompromiss zwischen Ausgabegröße und Anzahl der Aufrufe sein.

  2. Stellen Sie die erste Anfrage und geben Sie dabei eine Batchgröße von 1250 und eine Keep-Alive-Zeit für den Scroll-Kontext von 5 Minuten an:
    curl -k -X POST -d '{"size": "1250", "scroll": "5m"}' --url 'https://example.api.connect.com/analytics/analytics/cloud/events/scroll' -H 'Content-Type: application/json' -H 'Authorization: Bearer <bearer_token>'
    Gibt Folgendes zurück:
    {
    "total": 12453, # The total events found that match the query.
    "scroll_id": "<scroll_id>",
    "events": [...] # First batch of 1250 events.
}
  3. Machen Sie die zweite Anfrage und geben Sie dabei diescroll_id von der vorherigen Anfrage zurückgegeben:
    curl -k -X POST -d '{"size": "1250", "scroll": "5m", "scroll_id": "<scroll_id from previous response>"}' --url 'https://example.api.connect.com/analytics/analytics/cloud/events/scroll' -H 'Content-Type: application/json' -H 'Authorization: Bearer <bearer_token>'
  4. Wiederholen Sie die Anfrage noch 8 Mal und aktualisieren Sie diescroll_id jedes Mal mit der Ausgabe der vorherigen Anfrage.

    Da die Gesamtzahl der Ereignisse 12.453 beträgt und die Batchgröße 1.250 ist, gibt die letzte Anforderung nur 1.203 Ereignisse zurück.

    Alle nachfolgenden Anfragen, die Sie an denscroll_id Gibt ein leeres Ereignis-Array zurück.

  5. Löschen Sie den Scroll-Kontext:
    curl -k -X POST -d '{"scroll_id": "<scroll_id from previous response>"}' --url 'https://example.api.connect.com/analytics/analytics/cloud/events/scroll/delete' -H 'Content-Type: application/json' -H 'Authorization: Bearer <bearer_token>'

Leistungsvergleich von/events/scroll Und/events

Die folgenden Tabellen zeigen Leistungsvergleiche für die Abfrage von Analyseereignisdaten mithilfe von Skriptaufrufen. Bei den Zeiten handelt es sich um die Gesamtzeit zum Abrufen aller Ereignisdatensätze in Sekunden. Der/events Die API kann nicht mehr als 10.000 Ereignisse abrufen (und auch keine Stapel mit 1.000 oder mehr). Daher werden diese Felder als „n. z.“ markiert.
Notiz: Die Antwortzeiten Ihres Analysesubsystems können je nach Größe Ihrer API-Ereignisdatensätze, der Gesamtanzahl der Datensätze und Ihren verfügbaren Hardwareressourcen variieren.
Tabelle 1. Abruf von 1000 Ereignissätzen ( 5.3 MB)
Stapelgröße Anzahl der Aufrufe /eventsZeit /events/scrollZeit
100 10 7 9
500 2 3 4
1.000 1 nicht zutreffend 3
2.000 $ 1 nicht zutreffend 5
Tabelle 2. 10.000 Ereignissätze abrufen (26 MB)
Stapelgröße Anzahl der Aufrufe /eventsZeit /events/scrollZeit
100 100 67 75
500 20 Jahre 27. 32
1.000 10 nicht zutreffend 24
2.000 $ 5 nicht zutreffend 20 Jahre
Tabelle 3. 100.000 Ereignisdatensätze abrufen (265 MB)
Stapelgröße Anzahl der Aufrufe /eventsZeit /events/scrollZeit
100 1.000 nicht zutreffend 732
500 200 nicht zutreffend 299
1.000 100 nicht zutreffend 258
2.000 $ 50 nicht zutreffend 196
Tabelle 4. 760.265 Ereignissätze werden abgerufen (2 GB)
Stapelgröße Anzahl der Aufrufe /eventsZeit /events/scrollZeit
100 7603 nicht zutreffend 5647
500 1521 nicht zutreffend 2423
1.000 761 nicht zutreffend 2158
2.000 $ 381 nicht zutreffend 1919