Utilisation de l'opération de défilement des événements pour exporter des données d'analyse

Utilisez le/events/scroll opération pour exporter 10 000 enregistrements d’événements d’analyse ou plus avec l’API REST.

La méthode standard pour récupérer les données d'événements d'analyse avec leAPI Connect API REST d'analyse utilise le/events Appel API. Le/events L'appel API est optimisé pour une récupération rapide des données d'événement les plus récentes et est limité au renvoi d'un maximum de 10 000 enregistrements d'événements API. Si vous souhaitez récupérer plus de 10 000 enregistrements d'événements, utilisez l'outil/events/scroll API, optimisée pour la récupération de grands ensembles de données d'événements analytiques.

Lorsque vous interrogez vos données analytiques avec/events/scroll , OpenSearch trouve tous les enregistrements d'événements qui correspondent à votre requête et crée un pointeur appelé contexte de défilement. Vous utilisez ensuite le contexte de défilement pour récupérer les données d'événement par lots.

Important: La création de l'ensemble de résultats et du contexte de défilement utilise beaucoup de OpenSearch ressources. Il est recommandé de ne pas exécuter plusieurs/events/scroll requêtes simultanément et pour supprimer le contexte de défilement après la récupération de vos données d'événement.

Exportation d'événements d'analyse avec/events/scroll

Le/events/scroll L’opération renvoie les données d’événement par lots. Vous définissez la taille du lot lors du premier appel à/events/scroll , puis récupérez chaque lot lors des appels suivants. Vous devez passer chaque appel ultérieur au/events/scroll dans un certain temps, appelé temps de maintien du contexte de défilement. La procédure est la suivante :

  1. Faites le premier/events/scroll appel. Spécifiez la taille du lot et la durée de conservation pour l'opération de défilement. Par exemple, pour renvoyer les données d'événement par lots de 1 000 et conserver le contexte de défilement actif pendant 10 minutes, POSTEZ le JSON suivant sur/events/scroll :
    {
  "size": 1000, # Return the first 1000 event records.
  "scroll": 10m # Keep the scroll context alive for 10 minutes.
}
    • sizedéfinit la taille du lot.
    • scrolldéfinit le temps de maintien et utilise le format <nombre><unités>, Par exemple: 30s, 5m, 3h, 1d. La valeur maximale pourscroll est 1d.
    Exemple de réponse :
    {
    "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. Faire le prochain/events/scroll appeler en précisant lescroll_id de la réponse précédente :
    {
  "size": 1000,
  "scroll_id": "<as returned from previous call>",
  "scroll": 10m 
}
    L'API renvoie le prochain lot de 1 000 enregistrements d'événements et un nouveauscroll_id pour le prochain appel.
    Note: Si tonscroll_id est expiré, la réponse suivante est renvoyée :
    {
  "status": 404,
  "message": [
    {
      "trace": "7c7b3b11ee0e95b61452e8a78086d8e2",
      "errors": [
        {
          "code": "search_context_missing_exception",
          "message": "No search context found for id [48420]",
          "more_info": ""
        }
      ]
    }
  ]
}

    Si tonscroll_id expire, vous devez alors recommencer. Définissez une durée de conservation plus élevée pour le contexte de défilement afin de laisser plus de temps au renvoi des lots d'enregistrements d'événements et au suivant./events/scroll appel à faire.

  3. Continuez à faire/events/scroll appels, mise à jour duscroll_id à chaque fois avec la réponse de l'appel précédent.
  4. Après le dernier appel pour récupérer vos données d'événement, supprimez le contexte de défilement avec un POST pour/events/scroll/delete :
    {"scroll_id": "<as returned from previous call>"}
    Exemple de réponse :
    {
    "succeeded": true,
    "num_freed": 15
}
    Note: Le contexte de défilement est automatiquement supprimé à son expiration, mais si vous disposez d'une longue durée de conservation, il est recommandé de le supprimer explicitement pour libérer des ressources.

Exemple travaillé

L'exemple suivant montre comment vous pouvez utiliser lecurl commande pour récupérer manuellement vos données d'événement API à l'aide de la commande/events/scroll API.
Note: Pour de grandes quantités de données analytiques, récupération manuelle aveccurl est lent et sujet aux erreurs humaines. Une meilleure approche consiste à écrire un script pour que le/events/scroll appels et mettre à jour lescroll_id chaque appel. Voir https://ibm.biz/apic-analytics-events-scroll à titre d'exemple Python scénario.
  1. Obtenez le nombre total d'enregistrements d'événements pour décider de la taille de lot optimale et du nombre d'appels à effectuer :
    curl -k -X GET --url 'https://example.api.connect.com/analytics/analytics/cloud/events/count' -H 'Authorization: Bearer <bearer_token>'
    {
    "total": 12453
}

    Pour 12 453 événements, une taille de lot de 1 250 et un total de 10 appels peuvent constituer un bon équilibre entre la taille de la sortie et le nombre d'appels.

  2. Effectuez la première requête, en spécifiant la taille du lot de 1 250 et un temps de maintien du contexte de défilement de 5 minutes :
    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>'
    Retours :
    {
    "total": 12453, # The total events found that match the query.
    "scroll_id": "<scroll_id>",
    "events": [...] # First batch of 1250 events.
}
  3. Faites la deuxième demande en précisant lescroll_id renvoyé de la demande précédente :
    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. Répétez la demande 8 fois de plus, en mettant à jour lescroll_id avec la sortie de la requête précédente à chaque fois.

    Étant donné que le nombre total d’événements est de 12 453 et que la taille du lot est de 1 250, la dernière requête ne renvoie que 1 203 événements.

    Toute demande ultérieure que vous ferez auprès duscroll_id renvoie un tableau d'événements vide.

  5. Supprimez le contexte de défilement :
    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>'

Comparaison des performances de/events/scroll et/events

Les tableaux suivants présentent des comparaisons de performances pour l'interrogation des données d'événements d'analyse à l'aide d'appels scriptés. Les temps correspondent au temps total nécessaire pour récupérer tous les enregistrements d'événements en secondes. Le/events L'API ne peut pas récupérer plus de 10 000 événements (ni des lots de 1 000 ou plus), ces champs sont donc marqués comme n/a.
Note: Les temps de réponse sur votre sous-système d'analyse peuvent varier en fonction de la taille de vos enregistrements d'événements API, du nombre total d'enregistrements et de vos ressources matérielles disponibles.
Tableau 1. Récupération de 1 000 enregistrements d'événements (5.3 Mo)
Taille de lot Nombre d'appels /events heure /events/scroll heure
100 10 7 9
500 2 3 4
1 000 1 non disponible 3
2 000 1 non disponible 5
Tableau 2. Récupération de 10 000 enregistrements d'événements (26 Mo)
Taille de lot Nombre d'appels /events heure /events/scroll heure
100 100 65 75
500 20 27 32
1 000 10 non disponible 24
2 000 5 non disponible 20
Tableau 3. Récupération de 100 000 enregistrements d'événements (265 Mo)
Taille de lot Nombre d'appels /events heure /events/scroll heure
100 1 000 non disponible 732
500 200 non disponible 299
1 000 100 non disponible 258
2 000 50 non disponible 196
Tableau 4. Récupération de 760 265 enregistrements d'événements (2 Go)
Taille de lot Nombre d'appels /events heure /events/scroll heure
100 7603 non disponible 5647
500 1521 non disponible 2423
1 000 761 non disponible 2158
2 000 381 non disponible 1919