DeleteItem 删除文件-表格存储 Tablestore(Tablestore)-阿里云帮助中心

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
精确删除时使用精确 Scope，scope 的四级字段（appId、tenantId、agentId、runId）全部必填，不支持通配符 *；范围删除时使用包含通配符的 Scope。
精确删除可选 precondition.expectedVersionId 防止删除已被其他请求修改的文件。
范围删除为异步操作，成功受理返回 taskId 和 status: "pending"，不表示删除已完成。

请求参数

字段	类型	必填	说明
`itemId`	string	条件必填	精确删除时按文件稳定 ID 定位，与 `path` 二选一；范围删除时不传
`path`	string	条件必填	精确删除时按文件路径定位，与 `itemId` 二选一；范围删除时不传
`pathPrefix`	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>/DeleteItem \
  -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...",
  "precondition": {
    "expectedVersionId": "<latest-version-id>"
  }
}'

响应

精确删除成功响应扁平返回删除结果：

{
  "deleted": true,
  "itemId": "mem_01M2Z...",
  "type": "memoryfile"
}

范围删除成功受理返回 HTTP 200，响应包含 taskId 和 status：

{
  "type": "memoryfile",
  "taskId": "fmdel_<task-id>",
  "status": "pending"
}

字段	类型	说明
`type`	string	固定为 `memoryfile`
`taskId`	string	异步删除任务标识
`status`	string	受理时为 `pending`，不表示删除已完成

范围删除当前没有独立任务状态查询接口；请先停止目标范围写入，再使用同范围、同路径前缀的 ListItems 轮询，直到 items 为空且没有 nextToken。任务只完成一次单向扫描，持续发现残留时需重新发起删除。

需要同时清理历史时，先清空整个目标 Scope 内的当前文件，再调用 DeleteItemVersions 物理删除该范围内的全部版本。