功能概述

支持实时向特定数据集中新增或更新数据。系统会依据目标数据集主键值、和新数据记录主键值（如 “pk_id” = “2026aa01”）匹配：若主键值匹配成功，则更新该条数据记录；若匹配不存在，则新增该条数据记录。

接口说明

典型使用场景

场景	说明
数据实时新增	业务系统产生新数据时，实时推送到 AI 搜索平台
状态更新	业务端数据发生变更（如标题修改、状态下架）时，及时更新

前置说明

主键处理：根据目标数据集的主键类型（用户自定义或系统生成）来决定是执行新增还是更新操作。
批量限制：单次请求最多可处理 100 条记录。
Schema 匹配：传入的records具体数据项必须完全参照目标数据集在控制台配置的 Schema。
权限要求：确保拥有足够的权限对目标数据集进行写入或更新操作。
状态检查：在发起请求前，请确认目标数据集处于可写状态，而非只读模式。
支持格式范围和文件大小：请将资源转存为公开可访问 URL 后，通过 API 传入。系统支持解析的数据格式为：视频（MP4、AVI、MOV），实际单视频文件大小不超过 4 Gb；音频（MP3、AAC、M4A、WAV、FLAC、OGG、OPUS、WMA），实际单音频文件大小不超过 4 Gb；图片（JPG、JPEG、PNG、WEBP），实际单图片文件大小不超过 10 Mb。

请求参数

字段名称	字段类型	字段详情
body	object	请求体。
datasetId	string	数据集 ID，可在控制台数据集列表中查看。示例值：`730`
records	array<map<any>>	新增或更新的数据列表。一次批量操作最多不超过 100 条。说明：传入的 records 必须完全参照目标数据集在控制台配置的 Schema。具体的新增/更新逻辑取决于目标数据集的主键类型。详细示例请求见下方「请求说明」
map	<any>	具体数据项。
	any	数据项可以是任意格式。示例值： `[{` `"pk_id": "01KQCJXXX",` `"video_url": "https://sample.aliyun.com/path/test_1.mp4",` `"name": "new-test.mp4"` `}]`

请求说明

重要提示： records 数组内对象的字段要求：

records 字段内，每个具体数据项必须完全参照目标数据集在控制台配置的 Schema。具体的新增/ 更新路由逻辑取决于目标数据集的主键类型，分为以下两种情况。

情况一：用户自定义主键

假设用户在创建 datasetId 为 730 的数据集时，自定义了主键字段为 business_pk_id，则每条 records 中必须包含该主键字段及其对应的值。系统会根据主键值匹配目标数据集中的已有数据：

若未匹配到，则执行新增操作。
若匹配成功，则执行更新操作。

示例情景 1：新增一条数据

调用本 API 时，请求参数 records 中带有一行数据“business_pk_id”="NEW_ID_101"，由于系统在数据集中未找到 business_pk_id = "NEW_ID_101" 的记录，因此执行新增。

{
  "datasetId": 730,
  "records": [
    {
      "business_pk_id": "NEW_ID_101",
      "name": "new-video.mp4",
      "video_url": "https://example.com/new-video.mp4"
    }
  ]
}

示例情景 2：更新一条已有数据

调用本 API 时，请求参数 records 中带有一行数据“business_pk_id”="01KQCJBPM9JVDTXWV50G2AK"，由于系统在数据集中找到了 business_pk_id = "01KQCJBPM9JVDTXWV50G2AK" 的记录，因此执行更新。

{
  "datasetId": 730,
  "records": [
    {
      "business_pk_id": "01KQCJBPM9JVDTXWV50G2AK",
      "name": "updated-video.mp4",
      "video_url": "https://example.com/updated-video.mp4"
    }
  ]
}

情况二：系统自动生成主键（pk_id）

假设用户在创建 datasetId 为 750 的数据集时，选择使用系统自动生成的主键字段 pk_id。API 会根据参数 records 中记录是否携带 pk_id 字段进行分流处理：

携带 pk_id：系统将其视为更新操作，并在目标数据集中查找与该 pk_id 匹配的数据。若匹配成功则执行更新；若未匹配到，则返回 404 错误。
不携带 pk_id：系统将其视为新增操作，并自动为该条 Record 生成新的 pk_id 値。

示例情景 1：更新一条已有数据

携带 pk_id ，系统在数据集中匹配到对应记录，则执行更新。若未匹配到，则返回错误。

{
  "datasetId": 750,
  "records": [
    {
      "pk_id": "01KQCJBPM9JVDTXWV50G2AK",
      "name": "updated-video.mp4",
      "video_url": "https://example.com/updated-video.mp4"
    }
  ]
}

示例情景 2：新增一条数据

未携带 pk_id ，系统将该条记录视为新增，并自动生成 pk_id。

{
  "datasetId": 750,
  "records": [
    {
      "name": "new-video.mp4",
      "video_url": "https://example.com/new-video.mp4"
    }
  ]
}

响应参数

字段名称	字段类型	字段详情
code	integer<int32>	业务状态码。200 表示请求成功，其他值表示异常，详见错误码。示例值：`200`
message	string	状态描述。示例值：`success`
data	object	返回的数据主体，使用空占位符。示例值：`[]`
requestId	string	请求唯一标识，用于问题排查。示例值：`1a0f40dd17774641794394269ec0e9`

响应示例

{
  "code": 200,
  "message": "success",
  "data": {},
  "requestId": "1a0f40dd17774641794394269ec0e9"
}

错误码

错误码	message	说明	建议处理方式
400	datasetId: must not be null	请求参数不完整或格式错误。例如，缺少必需的 `datasetId` 参数。	检查您的请求，确保所有必填参数都已提供且格式正确。
400	Dataset is not ready, current status: {status}	目标数据集尚未准备就绪，无法接收数据。	请等待一段时间后重试，或在操作前检查数据集的状态。
400	Dataset schema is not configured	目标数据集没有配置数据结构（Schema）。	在上传数据前，请先为数据集定义并配置好相应的 Schema。
400	Exceeds maximum batch size of 100 records per request	单次请求上传的记录数量超过了 100 条的限制。	将您的数据分批处理，确保每个请求的记录数不超过 100 条。
400	records[{i}] cannot be empty	请求中的某条记录为空。	检查请求体中的 `records` 数组，确保其中没有空对象或空值。
400	records[{i}]: ...	请求中的某条记录数据不符合预设的 Schema 规范。	根据错误提示，检查并修正对应记录的字段名、数据类型等信息。
403	Dataset is read-only	目标数据集处于只读模式，不允许写入或更新操作。	请确认您是否有权限修改该数据集，或联系数据集管理员。
403	Access denied	访问被拒绝，通常是由于身份验证失败或权限不足。	检查您的 Access Key 或其他认证信息是否正确，并确认您有操作该资源的权限。
404	Dataset not found	指定的数据集不存在。	请检查请求中的 `datasetId` 是否正确。
404	pk_id not found	指定的数据集存在，但用户传入的`pk_id`不存在。	请检查请求对应的 `datasetId` 中，是否存在相应 `pk_id`。
500	Internal server error	服务器内部发生未知错误。	请稍后重试。如果问题持续存在，请联系技术支持。