AddItem 创建文件-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 AddItem 接口在文件记忆库中创建一个 UTF-8 文本文件或支持格式的二进制文件。content 和 contentBase64 必须且只能提供一个。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
文件操作使用精确 Scope，scope 的四级字段（appId、tenantId、agentId、runId）全部必填，不支持通配符 *。
读取文件内容时设置 view=full。

请求参数

字段	类型	必填	说明
`path`	string	是	以 `/` 开头的 Scope 内路径
`content`	string	条件必填	UTF-8 文本内容，可以是空字符串；与 `contentBase64` 二选一
`contentBase64`	string	条件必填	二进制文件原始内容的标准 Base64 编码；与 `content` 二选一
`mediaType`	string	条件必填	使用 `contentBase64` 时必填，且必须与路径扩展名和文件内容格式一致；取值见[支持的二进制格式](#支持的二进制格式)
`sessionId`	string	否	调用方会话或操作标识
`view`	string	否	响应视图

支持的二进制格式

扩展名	`mediaType`
`.pdf`	`application/pdf`
`.doc`	`application/msword`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.xls`	`application/vnd.ms-excel`
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.ppt`	`application/vnd.ms-powerpoint`
`.pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
`.jpg`、`.jpeg`	`image/jpeg`
`.png`	`image/png`

扩展名、mediaType 和文件内容格式必须一致。content 与 contentBase64 不能同时提供。

请求示例

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

curl -X POST https://<endpoint>/AddItem \
  -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"
  },
  "path": "/profile/preferences.md",
  "content": "# 用户偏好\n\n- 喜欢美式咖啡\n",
  "view": "full"
}'

创建二进制文件：

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

响应

成功响应包含 code、data 和 message。data 中返回创建的文件信息，使用 view=full 时文本文件通过 content 返回正文，二进制文件通过 contentBase64 和 mediaType 返回内容，不会返回 content。

{
  "code": "SUCCESS",
  "data": {
    "itemId": "mem_01K...",
    "path": "/profile/preferences.md",
    "content": "# 用户偏好\n\n- 喜欢美式咖啡\n"
  },
  "message": "succeed"
}

目标路径已存在时返回 409 PATH_EXISTS。二进制文件最大 2,000,000 字节。AddItem 只保存文件，不会自动构建 Wiki；Wiki 来源写入完成后需另行调用 IngestWiki。