增量同步数据

Change Feed 是面向外部客户应用的增量读取接口。应用通过 GET /v1/changes 主动拉取变化事件，成功处理完整一页后保存 next_cursor，再通过读取内容与历史获取正文或指标详情。

Change Feed 采用 pull-only 模式。MarsYoo 不通过 Webhook、消息队列回调或其他服务端机制向客户应用主动推送新数据。

当前事件

事件类型	触发条件	后续读取
`document.created`	首次创建标准文档	文档详情或 batch-get
`document.version.created`	标题、正文等内容产生新版本	指定 `version_id` 读取正文
`document.metrics.updated`	指标快照发生变化	文档 snapshots

删除、下架和不可用事件当前不作为可靠的客户数据源。只有平台采集器具备可靠复查信号后，才会正式开放相应事件。

首次读取

所有请求都需要 Consumer API Key：

Bash

export MARSYOO_BASE_URL='https://www.marsyoo.com'
export MARSYOO_API_KEY='whale_consumer_xxx'
 
curl --get "$MARSYOO_BASE_URL/v1/changes" \
  --header "Authorization: Bearer $MARSYOO_API_KEY" \
  --data-urlencode "dataset_id=social_media_raw" \
  --data-urlencode "event_type=document.created,document.version.created,document.metrics.updated" \
  --data-urlencode "limit=100"

首次读取不传 cursor，默认从在线保留窗口内最早的授权事件开始。

参数	说明
`cursor`	上一页返回的不透明 cursor；首次读取时省略
`limit`	每页 1–200 条，默认 100
`event_type`	逗号分隔的事件类型
`dataset_id`	逗号分隔的数据集 ID
`source_platform`	逗号分隔的平台枚举
`ingested_from` / `ingested_to`	按入库时间筛选，使用 RFC 3339 时间

接口只返回当前应用 entitlement 允许的数据集和平台。客户端不能通过筛选参数扩大授权范围。

响应与正文回源

JSON

{
  "items": [
    {
      "sequence": 42,
      "event_id": "chg_xxx",
      "schema_version": 1,
      "event_type": "document.version.created",
      "dataset_id": "social_media_raw",
      "source_platform": "reddit",
      "document_id": "doc_xxx",
      "version_id": "ver_xxx",
      "changed_fields": ["title", "body", "metadata"],
      "occurred_at": "2026-10-09T11:55:00Z",
      "observed_at": "2026-10-09T12:00:00Z",
      "ingested_at": "2026-10-09T12:00:02Z"
    }
  ],
  "next_cursor": "opaque-cursor"
}

事件只携带资源 ID 和变化字段名，不包含完整正文。建议将同一页中的 document_id 汇总后调用：

HTTP

POST /v1/documents/batch-get

需要读取事件对应的历史正文时，使用：

HTTP

GET /v1/documents/{document_id}/content?version_id={version_id}

Cursor 与 checkpoint

正确的消费顺序：

使用当前 cursor 请求一页事件。
幂等处理本页全部 items。
确认业务处理成功后持久化 next_cursor。
使用保存后的 cursor 请求下一页。

不要在处理完整页之前保存 cursor，否则进程故障时可能跳过事件。相同 cursor 可以安全重放并得到稳定页面；下游仍应使用 event_id 或业务资源 ID 做幂等。

Cursor 与 Consumer 应用及完整过滤条件绑定。更换 API Key 所属应用，或修改 event_type、数据集、平台、时间筛选后，不得继续复用旧 cursor。

错误处理

HTTP	含义	建议
`400`	参数、cursor 签名无效，或 cursor 与过滤条件不匹配	修正请求，不自动重试
`401`	API Key 缺失、无效或已撤销	更换有效密钥
`403`	应用没有目标数据范围权限	检查订阅和 entitlement
`410`	Cursor 已超出在线重放保留窗口	重新建立水位或使用历史数据恢复
`429`	触发频率、并发或配额限制	按 `Retry-After` 退避
`503`	Change Feed 暂时不可用	有限次数指数退避

在线事件当前保留 30 天。长期停止消费的应用必须监控 checkpoint 时间，避免超过保留窗口。

SDK 状态

当前正式支持的客户接入方式是 REST API 和公开 OpenAPI。Go/Python Consumer Client 已完成内部预览实现，但尚未发布公共下载地址、Go module 或独立 Python package，因此客户目前不能把它作为正式 SDK 安装使用。

在正式 SDK 发布前，请直接按本文档调用 GET /v1/changes，并由应用自行持久化 checkpoint。SDK 发布后，本页会补充可验证的版本号、安装命令和下载地址。

完整请求和 Schema 可在公开 API Reference中查看。