ListItemVersions 列出文件版本-表格存储 Tablestore(Tablestore)-阿里云帮助中心

使用 ListItemVersions 接口按 Scope 倒序列出文件的历史版本，支持按文件、会话、时间范围和操作类型过滤。

前提条件

已创建 AgentStorage 实例且状态为 normal，并获取实例访问地址（endpoint）和实例名。
已创建 API Key。
版本查询使用精确 Scope，scope 的四级字段（appId、tenantId、agentId、runId）全部必填，不支持通配符 *。范围版本删除清理后轮询时使用通配 Scope，参见 DeleteItemVersions。
读取版本内容时设置 view=full。

请求参数

字段	类型	必填	说明
`itemId`	string	否	只列出一个文件的版本
`sessionId`	string	否	按调用会话过滤
`createdAtGte` / `createdAtLte`	string	否	RFC3339 时间范围
`operation`	string	否	`created`、`modified` 或 `deleted`
`view`	string	否	`basic` 或 `full`
`limit`	int	否	默认 20，最大 100；`view=full` 时最大 20
`nextToken`	string	否	分页令牌

请求示例

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

curl -X POST https://<endpoint>/ListItemVersions \
  -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...",
  "limit": 20
}'

响应

版本响应包含自包含的 versionId、所属 itemId、操作类型、Scope、时间和操作者信息。

{
  "type": "memoryfile",
  "versions": [
    {
      "versionId": "<version-id>",
      "itemId": "mem_01M2Z...",
      "scope": { "appId": "app-001", "tenantId": "user-001", "agentId": "assistant", "runId": "run-001" },
      "operation": "modified",
      "path": "/profile/preferences.md",
      "contentSha256": "b43e966f...",
      "contentSizeBytes": 31,
      "createdAt": "2026-09-20T09:03:24Z"
    }
  ],
  "nextToken": "<next-token>"
}