UpdateItem 更新或重命名文件-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 UpdateItem 接口按 itemId 定位源文件，更新文件内容、目标路径或两者。未提供的字段保持不变。更新内容时，content 和 contentBase64 最多提供一个。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
文件操作使用精确 Scope，scope 的四级字段（appId、tenantId、agentId、runId）全部必填，不支持通配符 *。
更新内容或重命名时，建议通过 precondition.expectedVersionId 传入最近一次读取到的 latestVersionId 作为版本前置条件，防止覆盖其他请求的并发修改。
读取更新后的内容时设置 view=full。

请求参数

字段	类型	必填	说明
`itemId`	string	是	源文件稳定 ID
`content`	string	条件必填	新的 UTF-8 文本内容；与 `contentBase64` 二选一，并与 `path` 至少提供一个
`contentBase64`	string	条件必填	新二进制内容的标准 Base64 编码；与 `content` 二选一，并与 `path` 至少提供一个
`mediaType`	string	条件必填	使用 `contentBase64` 时必填，且必须与目标或现有路径的扩展名和文件内容格式一致；取值见[支持的二进制格式](./add-item.md#支持的二进制格式)
`path`	string	条件必填	新的目标路径；与任一内容字段至少提供一个
`precondition.expectedVersionId`	string	否	最近一次读取到的 `latestVersionId`
`overwrite`	boolean	否	目标路径存在时是否替换，默认 `false`；仅重命名时有效
`sessionId`	string	否	调用方会话或操作标识
`view`	string	否	响应视图

请求示例

使用 API Key 认证时，通过 x-ots-instancename 和 x-ots-apikey 请求头传入实例名和 API Key。

curl -X POST https://<endpoint>/UpdateItem \
  -H "x-ots-instancename: <instance-name>" \
  -H "x-ots-apikey: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "mem_01K...",
  "content": "# 用户偏好\n\n- 喜欢拿铁\n",
  "path": "/profile/user-preferences.md",
  "precondition": {
    "expectedVersionId": "<latest-version-id>"
  },
  "view": "full"
}'

将文件内容更新为 PDF：

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "session-001"
  },
  "itemId": "mem_01K...",
  "contentBase64": "<标准 Base64 编码的 PDF 内容>",
  "mediaType": "application/pdf",
  "path": "/documents/payment-spec.pdf",
  "view": "full"
}

响应

成功响应扁平返回更新后的文件信息。使用 view=full 时文本文件通过 content 返回正文，二进制文件通过 contentBase64 和 mediaType 返回内容，不会返回 content。使用 content 更新为文本后，响应不再返回 mediaType。

{
  "type": "memoryfile",
  "itemId": "mem_01M2Z...",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "assistant",
    "runId": "run-001"
  },
  "path": "/profile/user-preferences.md",
  "content": "# 用户偏好\n\n- 喜欢拿铁\n",
  "contentSha256": "b43e966f...",
  "contentSizeBytes": 31,
  "latestVersionId": "fmver3...",
  "createdAt": "2026-09-20T09:03:24Z",
  "updatedAt": "2026-09-20T09:03:24Z"
}

前置条件不匹配时返回 409 LOCK_CONFLICT。应用应重新读取文件，合并业务修改后再提交。二进制文件最大 2,000,000 字节。