跳至主要内容

批次匯出

資料量大到不適合分頁查詢時，用匯出。你建立工作、輪詢、下載檔案。請求欄位與 回應格式在 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 錯誤，或金鑰不擁有它。