Uso de la operación de desplazamiento de eventos para exportar datos analíticos

Utilizar el/events/scroll operación para exportar 10,000 o más registros de eventos analíticos con la API REST.

El método estándar para recuperar datos de eventos analíticos con elAPI Connect API REST de análisis está usando el/events Llamada API. El/events La llamada API está optimizada para una recuperación rápida de los datos de eventos más recientes y está limitada a devolver un máximo de 10 000 registros de eventos API. Si desea recuperar más de 10.000 registros de eventos, utilice el/events/scroll API, que está optimizada para la recuperación de grandes conjuntos de datos de eventos analíticos.

Cuando consulta sus datos analíticos con/events/scroll , OpenSearch encuentra todos los registros de eventos que coinciden con su consulta y crea un puntero que se llama contexto de desplazamiento. Luego utiliza el contexto de desplazamiento para recuperar los datos del evento en lotes.

Importante: La creación del conjunto de resultados y el contexto de desplazamiento utiliza muchos OpenSearch recursos. Se recomienda no ejecutar varios archivos diferentes./events/scroll consultas simultáneamente y para eliminar el contexto de desplazamiento después de que se recuperen los datos del evento.

Exportar eventos de análisis con/events/scroll

El/events/scroll La operación devuelve datos de eventos en lotes. Usted define el tamaño del lote en la primera llamada a/events/scroll y luego recuperar cada lote en llamadas posteriores. Debe realizar cada llamada posterior a/events/scroll dentro de un tiempo determinado, llamado tiempo de mantenimiento del contexto de desplazamiento. El procedimiento es el siguiente:

  1. haz el primero/events/scroll llamar. Especifique el tamaño del lote y el tiempo de mantenimiento de la operación de desplazamiento. Por ejemplo, para devolver datos de eventos en lotes de 1000 y mantener activo el contexto de desplazamiento durante 10 minutos, PUBLICAR el siguiente JSON en/events/scroll :
    {
  "size": 1000, # Return the first 1000 event records.
  "scroll": 10m # Keep the scroll context alive for 10 minutes.
}
    • sizedefine el tamaño del lote.
    • scrolldefine el tiempo de mantenimiento y utiliza el formato <número><unidades>, Por ejemplo: 30s, 5m, 3h, 1d. El valor máximo parascroll es 1d.
    Respuesta de ejemplo:
    {
    "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. hacer el siguiente/events/scroll llamar, especificando elscroll_id de la respuesta anterior:
    {
  "size": 1000,
  "scroll_id": "<as returned from previous call>",
  "scroll": 10m 
}
    La API devuelve el siguiente lote de 1000 registros de eventos y un nuevoscroll_id para la próxima llamada.
    Nota: Si tuscroll_id ha caducado, se devuelve la siguiente respuesta:
    {
  "status": 404,
  "message": [
    {
      "trace": "7c7b3b11ee0e95b61452e8a78086d8e2",
      "errors": [
        {
          "code": "search_context_missing_exception",
          "message": "No search context found for id [48420]",
          "more_info": ""
        }
      ]
    }
  ]
}

    Si tuscroll_id expira, entonces debes comenzar de nuevo. Establezca un tiempo de mantenimiento más alto para el contexto de desplazamiento para permitir más tiempo para que se devuelvan los lotes de registros de eventos y el siguiente/events/scroll llamada a realizar.

  3. continuar haciendo/events/scroll llamadas, actualizando elscroll_id cada vez con la respuesta de la llamada anterior.
  4. Después de la última llamada para recuperar los datos de su evento, elimine el contexto de desplazamiento con una POST para/events/scroll/delete :
    {"scroll_id": "<as returned from previous call>"}
    Respuesta de ejemplo:
    {
    "succeeded": true,
    "num_freed": 15
}
    Nota: El contexto de desplazamiento se elimina automáticamente cuando caduca, pero si tiene un tiempo de mantenimiento prolongado, se recomienda eliminarlo explícitamente para liberar recursos.

Ejemplo resuelto

El siguiente ejemplo muestra cómo puede utilizar elcurl comando para recuperar manualmente los datos de su evento API utilizando el/events/scroll API.
Nota: Para grandes cantidades de datos analíticos, la recuperación manual concurl es lento y propenso a errores humanos. Un mejor enfoque es escribir un guión para hacer/events/scroll llamadas y actualizar elscroll_id cada llamada. Ver https://ibm.biz/apic-analytics-events-scroll para un ejemplo Python guion.
  1. Obtenga un recuento del total de registros de eventos para decidir el tamaño de lote óptimo y la cantidad de llamadas a realizar:
    curl -k -X GET --url 'https://example.api.connect.com/analytics/analytics/cloud/events/count' -H 'Authorization: Bearer <bearer_token>'
    {
    "total": 12453
}

    Para 12453 eventos, un tamaño de lote de 1250 y un total de 10 llamadas pueden ser un buen equilibrio entre el tamaño de la salida y la cantidad de llamadas.

  2. Realice la primera solicitud, especificando el tamaño del lote de 1250 y un tiempo de mantenimiento del contexto de desplazamiento de 5 minutos:
    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>'
    Devuelve:
    {
    "total": 12453, # The total events found that match the query.
    "scroll_id": "<scroll_id>",
    "events": [...] # First batch of 1250 events.
}
  3. Realizar la segunda solicitud, especificando elscroll_id devuelto de la solicitud anterior:
    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. Repita la solicitud 8 veces más, actualizando elscroll_id con el resultado de la solicitud anterior cada vez.

    Dado que el total de eventos es 12453 y el tamaño del lote es 1250, la última solicitud devuelve solo 1203 eventos.

    Cualquier solicitud posterior que realice con elscroll_id Devuelve una matriz de eventos vacía.

  5. Eliminar el contexto de desplazamiento:
    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>'

Comparación de rendimiento de/events/scroll y/events

Las siguientes tablas muestran comparaciones de rendimiento para consultar datos de eventos de análisis mediante llamadas programadas. Los tiempos son el tiempo total para recuperar todos los registros de eventos en segundos. El/events La API no puede recuperar más de 10000 eventos (ni lotes de 1000 o más), por lo que estos campos están marcados como n/a.
Nota: Los tiempos de respuesta en su subsistema de análisis pueden variar según el tamaño de sus registros de eventos API, la cantidad total de registros y sus recursos de hardware disponibles.
Tabla 1. Obteniendo 1000 registros de eventos (5.3 Megabyte)
Tamaño de lote Número de llamadas /events hora /events/scroll hora
100 10 7 9
500 2 3 4
1000 1 n/d 3
2000 1 n/d 5
Tabla 2. Obteniendo 10.000 registros de eventos (26 Mb)
Tamaño de lote Número de llamadas /events hora /events/scroll hora
100 100 67 75
500 20 27 premios 32
1000 10 n/d 24
2000 5 n/d 20
Tabla 3. Obteniendo 100.000 registros de eventos (265 Mb)
Tamaño de lote Número de llamadas /events hora /events/scroll hora
100 1000 n/d 732
500 200 n/d 299
1000 100 n/d 258
2000 50 n/d 196
Tabla 4. Obteniendo 760.265 registros de eventos (2 GB)
Tamaño de lote Número de llamadas /events hora /events/scroll hora
100 7603 n/d 5647
500 1521 n/d 2423
1000 761 n/d 2158
2000 381 n/d 1919