# 创建同步任务

为一个 Langfuse 连接器创建 Trace 同步任务。每个连接器最多关联一个任务；平台自动创建目标数据库和表，并注册相应的 Trace 数据资产。

```text
POST https://moi.matrixorigin.cn/newmoi/trace-sync/tasks
```

## 调用前准备

先[创建连接器](../connectors/create-connector.md)并确认其来源类型为 Langfuse。准备有目标工作区访问权限的个人访问令牌、目标工作区 ID 和 Langfuse 连接器 ID。

下方示例使用：

- `$AI_STUDIO_API_KEY`：实际个人访问令牌，通过 `X-API-Key` Header 传递。
- `$WORKSPACE_ID`：目标工作区 ID，通过 `X-Workspace-ID` Header 传递。
- `$CONNECTOR_ID`：要建立同步任务的 Langfuse 连接器 ID。

调用者需要具备该连接器的使用权限。创建任务只启用 Trace 同步，不会自动启用记忆提取。

## 请求体

| 参数 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `connector_id` | string | 是 | Langfuse 连接器 ID。 |
| `name` | string | 是 | 任务名称；平台据此生成目标表名称。 |
| `sync_historical` | boolean | 否 | 是否同步历史数据；默认 `false`。 |
| `start_from` | string | 否 | 历史同步起始时间，采用 RFC 3339 格式。 |
| `user_id_source` | string | 否 | 用户标识来源，可取 `user_id` 或 `metadata`；默认 `metadata`。 |
| `user_id_metadata_key` | string | 否 | `user_id_source` 为 `metadata` 时使用的 metadata 键；未填写则默认为 `customer_id`。 |
| `poll_interval_sec` | integer | 否 | 拉取间隔秒数；填写正整数，未填写或不大于 0 时使用 `60`。 |

目标 Catalog、数据库和表由平台管理，不能通过本接口指定。

## 请求示例

```bash
curl -X POST "https://moi.matrixorigin.cn/newmoi/trace-sync/tasks" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "connector_id": "'"$CONNECTOR_ID"'",
    "name": "production-traces",
    "sync_historical": true,
    "start_from": "2026-08-01T00:00:00Z",
    "user_id_source": "metadata",
    "user_id_metadata_key": "customer_id",
    "poll_interval_sec": 60
  }'
```

## 成功响应

成功时返回新任务及平台分配的目标位置。初始同步状态为尚未开始，后台同步器随后按配置拉取 Trace。

```json
{
  "code": "OK",
  "msg": "OK",
  "data": {
    "id": "task_01",
    "connector_id": "conn_01",
    "name": "production-traces",
    "catalog_name": "trace_catalog",
    "database_name": "langfuse_trace_db",
    "table_name": "lf_production_traces",
    "sync_historical": true,
    "start_from": "2026-08-01T00:00:00Z",
    "user_id_source": "metadata",
    "user_id_metadata_key": "customer_id",
    "poll_interval_sec": 60,
    "session_idle_timeout_sec": 300,
    "session_end_strategy": "idle_timeout",
    "session_end_metadata_key": "session_end",
    "session_end_metadata_value": "ended",
    "sync_status": "not_started",
    "auto_extract_enabled": false,
    "created_by": "user_01",
    "created_at": "2026-08-21T08:00:00Z",
    "updated_at": "2026-08-21T08:00:00Z",
    "session_count": 0
  }
}
```

响应字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `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 | 同步状态：`not_started`、`catching_up`、`steady` 或 `error`。 |
| `data.last_synced_to` | string | 最近同步水位；尚无水位时省略。 |
| `data.last_success_at` | string | 最近成功时间；尚未成功时省略。 |
| `data.last_error` | string | 最近错误；没有错误时省略。 |
| `data.auto_extract_enabled` | boolean | 是否启用自动记忆提取；新建任务为 `false`。 |
| `data.created_by` | string | 创建者 ID。 |
| `data.created_at` | string | 创建时间，采用 RFC 3339 格式。 |
| `data.updated_at` | string | 更新时间，采用 RFC 3339 格式。 |
| `data.session_count` | integer | 已发现的同步会话数量。 |

## 错误响应

```json
{
  "code": "CONNECTOR_NOT_LANGFUSE",
  "msg": "invalid parameter",
  "data": null
}
```

### 常见 HTTP 错误

```{list-table}
:header-rows: 1
:widths: 12 25 35 28

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - `ErrIAMRequestInvalid`
  - 请求缺少可供权限校验的 `connector_id`，或请求体格式无效。
  - 提供有效连接器 ID 和 JSON 请求体。
* - `400`
  - `CONNECTOR_NOT_LANGFUSE`、`PARAM_INVALID`
  - 连接器类型不受支持，或用户标识映射参数无效。
  - 使用 Langfuse 连接器，并检查用户标识配置。
* - `403`
  - `FORBIDDEN`
  - 调用者无权使用该连接器。
  - 为当前身份授予连接器使用权限。
* - `404`
  - `CONNECTOR_NOT_FOUND`
  - 连接器不存在或不属于当前工作区。
  - 检查工作区和连接器 ID。
* - `409`
  - `TASK_ALREADY_EXISTS`
  - 该连接器已经有关联任务。
  - 使用[按连接器查询同步任务](list-connector-sync-tasks.md)取得现有任务。
* - `500`
  - `INTERNAL`
  - 平台未能创建目标对象、任务或 Trace 数据资产。
  - 稍后重试；重复失败时联系管理员。
* - `503`
  - `IAM_UNAVAILABLE`
  - 权限服务暂时不可用。
  - 稍后重试。
```

## 后续操作

记录 `data.id`。使用它[查询同步任务详情](get-sync-task.md)，或使用连接器 ID [查询同步状态](get-sync-status.md)；需要调整拉取配置时[更新同步任务](update-sync-task.md)。