DeleteItemVersions 批量删除文件版本-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 DeleteItemVersions 接口按通配 Scope 异步物理删除文件记忆的全部历史版本，删除后不可恢复。适用于清理一个租户或一个 Agent 下所有会话的文件历史。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
本接口仅适用于可写文件记忆库。scope 必须包含通配符 *，scope.appId、scope.tenantId 必须为确定值，不支持精确 Scope、跨应用或跨租户删除。
调用前必须先清空同一范围内的当前文件；范围内仍有当前文件时，接口返回冲突且不受理删除任务。
范围删除为异步操作，成功受理返回 taskId 和 status: "pending"，不表示版本已删除完成。
公共请求头与认证方式参见使用 API。

请求参数

字段	类型	必填	说明
`type`	string	是	固定为 `memoryfile`
`memoryStoreName`	string	是	待清理的文件记忆库名称
`scope`	object	是	待清理范围，必须包含通配符 `*`，规则见下文

scope.appId、scope.tenantId 必须为确定值。使用以下两种 Scope 指定范围，建议显式填写四级字段：

删除范围	`appId`	`tenantId`	`agentId`	`runId`
一个 Agent 下全部会话的版本	指定应用	指定租户	指定 Agent	`*`
一个租户下全部 Agent、全部会话的版本	指定应用	指定租户	`*`	`*`

出现 * 后，右侧层级也应填写 *。不支持无通配符的精确 Scope，也不支持跨应用或跨租户删除。每个 Scope 字段最长 128 字节，不得包含 / 或 NUL。

请求只接受 type、memoryStoreName 和 scope，不接受 itemId、versionId、path、pathPrefix、sessionId、时间范围、operation、filter、precondition 或其他额外字段。无法按单个文件、目录或版本条件缩小删除范围。

请求示例

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

curl -X POST https://<endpoint>/DeleteItemVersions \
  -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": "*",
    "runId": "*"
  }
}'

响应

成功受理返回 HTTP 200，响应体如下，不包含 code、data 外层包装：

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

字段	类型	说明
`type`	string	固定为 `memoryfile`
`taskId`	string	异步删除任务标识，可保存用于诊断追踪
`status`	string	受理时为 `pending`，不表示版本已经删除完成

清理流程与完成判断

1. 停止目标范围内的文件写入，并在整个清理过程中保持停写。

2. 使用相同的 memoryStoreName 和 scope 调用范围 DeleteItem，不传 pathPrefix，清理该范围内的全部当前文件。

3. 使用相同范围轮询 ListItems，不添加路径或其他过滤条件，确认 items 为空且没有 nextToken。若返回分页令牌，应继续检查后续页，不能把一个空页当作范围已清空。

4. 调用 DeleteItemVersions，保存返回的 taskId。

5. 使用相同范围轮询 ListItemVersions，不添加 itemId、path、sessionId、时间或操作类型等过滤条件，直到 versions 为空且没有 nextToken。

范围删除当前没有独立的任务状态查询接口。taskId 不能作为 GetMemoryTask 的 requestId 查询；应以上述列表结果判断清理是否完成。

例如，第 5 步向 POST /ListItemVersions 发送以下请求，每轮轮询从第一页开始：

{
  "type": "memoryfile",
  "memoryStoreName": "agent_files",
  "scope": {
    "appId": "app-001",
    "tenantId": "user-001",
    "agentId": "*",
    "runId": "*"
  },
  "view": "basic",
  "limit": 20
}

清理完成时，列表响应为：

{
  "type": "memoryfile",
  "versions": []
}

设置合理的轮询间隔和总超时。范围 DeleteItem 和 DeleteItemVersions 在同一实例、同一租户内串行执行；每个任务只完成一次单向扫描，不会在扫描结束后自动重新清理整个范围。若持续发现残留，应确认写入已停止，再重新发起对应的删除操作。物理删除版本前，仍需先确认当前文件为空。