使用事件滚动操作导出分析数据

使用 /events/scroll 操作，通过 REST API 导出 10,000 条或更多分析事件记录。

使用 API Connect Analytics REST API 检索分析事件数据的标准方法是使用 /events API 调用。 /events API 调用针对快速检索最新事件数据进行了优化，最多只能返回 10,000 条 API 事件记录。 如果要检索 10,000 条以上的事件记录，请使用 /events/scroll API，该 API 已针对检索大型分析事件数据集进行了优化。

当您使用 /events/scroll 查询分析数据时，OpenSearch 会找到与您的查询相匹配的所有事件记录，并创建一个称为滚动上下文的指针。 然后，您可以使用滚动上下文分批检索事件数据。

重要：创建结果集和滚动上下文使用了大量 OpenSearch资源。 建议不要同时运行多个不同的 /events/scroll 查询，并在获取事件数据后删除滚动上下文。

使用 /events/scroll 导出分析事件

/events/scroll 操作会分批返回事件数据。 您可以在第一次调用 /events/scroll 时定义批次大小，然后在后续调用中检索每个批次。 您必须在一定时间内对 /events/scroll 进行每次后续调用，该时间称为滚动上下文保持连接时间。 程序如下

  1. 进行第一次 /events/scroll 调用。 指定滚动操作的批量大小和保持连接时间。 例如，要以 1000 为一批返回事件数据，并在 10 分钟内保持滚动上下文的活力，可将以下 JSON 发送到 /events/scroll：
    {
  "size": 1000, # Return the first 1000 event records.
  "scroll": 10m # Keep the scroll context alive for 10 minutes.
}
    • size 定义批量大小。
    • scroll 定义保持连接时间并使用 <number><units> 格式，例如：30s, 5m, 3h, 1d. scroll 的最大值为 1d 。
    响应示例：
    {
    "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. 进行下一次 /events/scroll 调用，指定上一个响应中的 scroll_id ：
    {
  "size": 1000,
  "scroll_id": "<as returned from previous call>",
  "scroll": 10m 
}
    API 会返回下一批 1000 条事件记录，并返回一个新的 scroll_id 供下一次调用。
    注意： 如果您的 scroll_id 过期，将返回以下响应：
    {
  "status": 404,
  "message": [
    {
      "trace": "7c7b3b11ee0e95b61452e8a78086d8e2",
      "errors": [
        {
          "code": "search_context_missing_exception",
          "message": "No search context found for id [48420]",
          "more_info": ""
        }
      ]
    }
  ]
}

    如果您的 scroll_id 过期，则必须重新开始。 为滚动上下文设置更长的保持连接时间，以便有更多时间返回事件记录批次和进行下一次 /events/scroll 调用。

  3. 继续调用 /events/scroll，每次都用上一次调用的响应更新 scroll_id 。
  4. 在最后一次调用检索事件数据后，通过 POST 到 /events/scroll/delete 删除滚动上下文：
    {"scroll_id": "<as returned from previous call>"}
    响应示例：
    {
    "succeeded": true,
    "num_freed": 15
}
    注意：滚动上下文会在过期时自动删除，但如果保持连接的时间较长，则建议明确删除以释放资源。

工作实例

下面的示例展示了如何使用 curl 命令，通过 /events/scroll API 手动检索 API 事件数据。
注意：对于大量分析数据，使用 curl 进行手动检索不仅速度慢，而且容易出现人为错误。 更好的方法是编写一个脚本来调用 /events/scroll，并在每次调用时更新 scroll_id。 有关 Python 脚本的示例，请参阅 https://ibm.biz/apic-analytics-events-scroll 。
  1. 统计事件记录总数，以确定最佳批量大小和调用次数：
    curl -k -X GET --url 'https://example.api.connect.com/analytics/analytics/cloud/events/count' -H 'Authorization: Bearer <bearer_token>'
    {
    "total": 12453
}

    对于 12453 个事件，批量大小为 1250 个，总调用次数为 10 次，这可能是输出大小和调用次数之间的良好平衡。

  2. 发出第一个请求，指定批量大小为 1250，滚动上下文保持有效时间为 5 分钟：
    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>'
    返回：
    {
    "total": 12453, # The total events found that match the query.
    "scroll_id": "<scroll_id>",
    "events": [...] # First batch of 1250 events.
}
  3. 进行第二次请求，指定上一次请求返回的 scroll_id ：
    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. 再重复请求 8 次，每次都用上一次请求的输出更新 scroll_id 。

    由于事件总数为 12453 个，批量大小为 1250 个，最后一个请求只返回 1203 个事件。

    使用 scroll_id 提出的任何后续请求都会返回一个空事件数组。

  5. 删除滚动上下文：
    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>'

/events/scroll 和 /events 的性能比较

下表显示了使用脚本调用查询分析事件数据的性能比较。 时间是检索所有事件记录的总时间，单位为秒。 /events API 无法检索超过 10000 个事件（也无法检索 1000 个或更多批次），因此这些字段被标记为 n/a。
注意：分析子系统的响应时间可能会因 API 事件记录的大小、记录总数和可用硬件资源而异。
表 1. 获取 1000 条事件记录（5.3 Mb）
批处理大小 调用数 /events time /events/scroll time
100 10 7 9
500 2 3 4
1000 1 不适用 3
2000 1 不适用 5
表 2. 获取 10,000 条事件记录（26 Mb）
批处理大小 调用数 /events time /events/scroll time
100 100 67 75
500 20 27 日 32
1000 10 不适用 24
2000 5 不适用 20
表 3. 获取 100,000 条事件记录 (265 Mb)
批处理大小 调用数 /events time /events/scroll time
100 1000 不适用 732
500 200 不适用 299
1000 100 不适用 258
2000 50 不适用 196
表 4. 获取 760,265 条事件记录（2 GB）
批处理大小 调用数 /events time /events/scroll time
100 7603 不适用 5647
500 1521 不适用 2423
1000 761 不适用 2158
2000 381 不适用 1919