按需查阅，不是必读接入步骤。接入路线：[查询取数接入路线](/docs)

# 增量同步数据

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

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

正确的消费顺序：

1. 使用当前 cursor 请求一页事件。
2. 幂等处理本页全部 `items`。
3. 确认业务处理成功后持久化 `next_cursor`。
4. 使用保存后的 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](/public-api-reference)中查看。

## 继续当前任务

[返回接入路线](/docs)；查完所需信息后，回到正在执行的步骤。