更新同步任务

更新一个 Langfuse Trace 同步任务的名称、历史范围、用户标识映射或拉取间隔。连接器和目标位置在创建后不能修改。

PUT https://moi.matrixorigin.cn/newmoi/trace-sync/tasks/{id}

调用前准备

先查询同步任务详情取得任务 ID 和当前配置。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和同步任务 ID。

下方示例使用：

• $AI_STUDIO_API_KEY：实际个人访问令牌，通过 X-API-Key Header 传递。

• $WORKSPACE_ID：目标工作区 ID，通过 X-Workspace-ID Header 传递。

• $TASK_ID：要更新的同步任务 ID。

调用者需要具备任务关联连接器的更新权限。请求只更新明确提交的字段；空对象会返回当前任务而不修改配置。

路径参数

参数	类型	是否必填	说明
id	string	是	同步任务 ID。

请求体

参数	类型	是否必填	说明
name	string	否	新任务名称；不能是空字符串。更新名称不会重命名已分配的目标表。
sync_historical	boolean	否	是否同步历史数据。
start_from	string	否	历史同步起始时间，采用 RFC 3339 格式。
user_id_source	string	否	用户标识来源，可取 user_id 或 metadata。
user_id_metadata_key	string	条件必填	使用 metadata 来源时的键；与已有值合并后必须有效。
poll_interval_sec	integer	否	拉取间隔秒数，必须为正整数。

请求示例

curl -X PUT "https://moi.matrixorigin.cn/newmoi/trace-sync/tasks/$TASK_ID" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "production-traces-hourly",
    "poll_interval_sec": 3600
  }'

成功响应

成功时返回更新后的完整任务。正在进行的同步会在持久化下一批数据前使用最新配置。

{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "task_01",
    "connector_id": "conn_01",
    "name": "production-traces-hourly",
    "catalog_name": "trace_catalog",
    "database_name": "langfuse_trace_db",
    "table_name": "lf_production_traces",
    "sync_historical": true,
    "user_id_source": "metadata",
    "user_id_metadata_key": "customer_id",
    "poll_interval_sec": 3600,
    "session_idle_timeout_sec": 300,
    "session_end_strategy": "idle_timeout",
    "session_end_metadata_key": "session_end",
    "session_end_metadata_value": "ended",
    "sync_status": "steady",
    "auto_extract_enabled": false,
    "created_by": "user_01",
    "created_at": "2026-08-20T08:00:00Z",
    "updated_at": "2026-08-21T08:10:00Z",
    "session_count": 12
  }
}

响应字段如下。

字段	类型	说明
code	string	成功时为 OK。
msg	string	成功时为 OK。
data.id	string	同步任务 ID。
data.connector_id	string	关联的连接器 ID。
data.name	string	更新后的任务名称。
data.catalog_name	string	目标 Catalog 名称。
data.database_name	string	目标数据库名称。
data.table_name	string	目标表名称。
data.sync_historical	boolean	是否同步历史数据。
data.start_from	string	历史同步起始时间；未设置时省略。
data.user_id_source	string	用户标识来源。
data.user_id_metadata_key	string	metadata 用户标识键。
data.poll_interval_sec	integer	拉取间隔秒数。
data.session_idle_timeout_sec	integer	会话空闲结束阈值，单位为秒。
data.session_end_strategy	string	会话结束判定策略。
data.session_end_metadata_key	string	显式结束会话使用的 metadata 键。
data.session_end_metadata_value	string	显式结束会话匹配的 metadata 值。
data.sync_status	string	同步状态。
data.last_synced_to	string	最近同步水位；尚无水位时省略。
data.last_success_at	string	最近成功时间；尚未成功时省略。
data.last_error	string	最近错误；没有错误时省略。
data.auto_extract_enabled	boolean	是否启用自动记忆提取。
data.created_by	string	创建者 ID。
data.created_at	string	创建时间。
data.updated_at	string	更新时间。
data.session_count	integer	已发现的同步会话数量。

错误响应

{
  "code": "PARAM_INVALID",
  "msg": "invalid parameter",
  "data": null
}

常见 HTTP 错误

HTTP 状态码	错误代码	常见原因	建议操作
400	PARAM_INVALID	名称为空、拉取间隔不为正数，或用户标识映射无效。	修正提交字段后重试。
403	FORBIDDEN	调用者无权更新任务关联的连接器。	联系管理员检查连接器更新权限。
404	NOT_FOUND	任务不存在或不属于当前工作区。	检查工作区和任务 ID。
500	INTERNAL	平台未能保存更新。	稍后重试。
503	IAM_UNAVAILABLE	权限校验所需的任务或权限服务暂时不可用。	稍后重试。

后续操作

使用 data.id 查询同步任务详情确认保存结果；使用 data.connector_id 查询同步状态观察后续同步。

最后更新于 2026 年 8 月 22 日