跳到主要内容

批量导出

数据量大到不适合分页查找时，用导出。你创建工作、轮询、下载文件。请求字段与 响应格式在 API 文档；本页说明流程与预期行为。

创建工作​

H="Authorization: Bearer $VEINMESH_API_KEY"
API=https://data.cyberun.cloud

curl -s -H "$H" -H "Content-Type: application/json" \
  -X POST "$API/v2/exports" \
  -d '{
    "dataset": "book.snapshot",
    "symbols": ["SHFE.rb2701", "SHFE.rb2705"],
    "from_day": "2026-09-01",
    "to_day": "2026-10-20",
    "format": "parquet"
  }' | jq '{export_id, status}'

响应是工作，含 export_id 与状态：queued、running、done、failed 或 expired。工作属于创建它的密钥。

追踪​

curl -s -H "$H" "$API/v2/exports/<export_id>" | jq '{status, rows, files, error}'

工作 running 时，pending 显示还剩多少 instrument-day 要读。每隔几秒轮询； 不要重复创建同一个工作。

done 时响应有：

  • rows：写入的总列数；
  • files：一或多个文件，含 index、列数与 SHA-256；
  • partitions：工作读取的分区版本，用于重现。

下载​

GET /v2/exports/{export_id}/files/{file_index}

文件经由 gateway 流，你不会拿到 bucket URL。file index 用工作响应里的。

  • 工作还在跑：下载回 503 data_pending。
  • 工作已过期：回 404 not_found。
  • file index 不在工作文件清单：404 not_found。

格式与大小​

  • parquet：有类型字段，小数是 DECIMAL(38,9)，时间是 UTC 奈秒。
  • csv：一列标头；list 字段展开成每层一栏（bid_px_1、bid_px_2…）。

较大的工作会切成多个文件。请下载全部文件；工作响应的列数才是 总数。导出完成后保留有限时间；见限制。

可以导出什么​

创建工作时会验证数据集、商品与区间：

  • 数据集必须是该商品有的；
  • 商品必须在区间的 as_of 日可解析；
  • 区间必须在导出限制内；
  • 连续代号（.main、.cN）会逐交易日解析成合约片段（一次导出只能有一个连续代号；不接受 instant 区间）。每行保留连续 symbol；instrument_id 是解析到的合约，换月时会变。

商品数、区间与保留期限见限制。

Python​

job = client.export("book.snapshot", ["SHFE.rb2701", "SHFE.rb2705"],
                    from_day="2026-09-01", to_day="2026-10-20", format="parquet")
df = job.wait().to_pandas()       # 下载并合并文件
files = job.download("./data")    # 或保留文件

job.wait() 轮询到完成；client.get_export(id) 可在另一个进程重开工作。 to_pandas(exact=True) 保留 Decimal。

失败​

failed 工作带 error 字符串。若还需要这个范围就重新提交；失败的工作不会自己 重试。查工作得到 not_found 代表 id 错误，或密钥不拥有它。