Immutable Storage

Authentication

参考接入 BytePower

功能概述

为用户提供按 content_key 分组、以毫秒级 time_key 索引的时序数据存储能力，适合记录日志、历史快照、版本化数据等不可变/弱变更场景，提供易用的 API。

• 数据可见性约束：超过 6 个月（180 天）的数据不会出现在查询结果中。
• 数据与字段限制：单条 content_value 与 note 字段最大 2MB；单次请求 items 最多 10 条。
• 支持批量创建或追加
• 支持时间区间查询，内置分页：每页 50 条，使用 next_cursor 继续翻页。
• 支持查询指定 content_key 的全部 time_key，以及按给定 time_key 集合精确获取数据。
• 支持批量删除：可删除某用户全部数据、某个 content_key 下的数据，或某个 content_key + time_key 的单条数据。

API

注意，超过6个月即180天的数据不会显示在结果内

创建/追加

Method & Path

• POST {domain}/bp/storage/immutable/append
• POST {domain}/bp/server/user/{user_id}/storage/immutable/append如果没有key则创建，最多10个

content_value，note 最大 2MB

请求示例:

{
  "content_key": "name",
  "items": [
    {
      "content_value": "zzb",
      "time_key": 1628057604000,
      "note1": "xxx",
      "note2": "xxx",
      "note3": "xxx"
    },
    {
      "content_value": "wzy",
      "time_key": 1628057605000
    }
  ]
}

返回示例：

{
  "success": [
    {
      "time_key": 1628057604000
    },
    {
      "time_key": 1628057605000
    }
  ],
  "failure": [
    {
      "time_key": 1628057605000,
      "error": "xxx"
    }
  ],
  "total": 3
}

创建/更新

Method & Path

• POST {domain}/bp/storage/immutable/save
• POST {domain}/bp/server/user/{user_id}/storage/immutable/save有key更新，无key创建，最多10个

请求示例:

{
  "content_key": "name",
  "items": [
    {
      "content_value": "wzy",
      "time_key": 1628057604000,
      "note1": "xxx",
      "note2": "iii",
      "note3": "qqq"
    }
  ]
}

返回示例：

{
  "created": [
    {
      "time_key": 1628057604000
    }
  ],
  "updated": [
    {
      "time_key": 1628057605000,
      "changed": [
        "note1"
      ]
    }
  ],
  "failure": [
    {
      "time_key": 1628057605000,
      "error": "xxx"
    }
  ],
  "total": 3
}

获取

Method & Path

• POST {domain}/bp/storage/immutable/query
• POST {domain}/bp/server/user/{user_id}/storage/immutable/query

request body

参数	类型	说明
time_key_start	int	毫秒级时间戳
time_key_end	int	毫秒级时间戳
cursor	int	前次请求获取的next_cursor，首次请求时为null

请求示例:

{
  "content_key": "name",
  "time_key_start": 1628057605000,
  "time_key_end": 1628057607000,
  "cursor": null
}

获取[time_key_start, time_key_end]区间的数据，不传则返回全量。 每页50条，服务器每次查询多取一条作为next_cursor的依据。

返回示例:

{
  "immutable_storage_items": [
    {
      "user_id": "xxx",
      "content_key": "name",
      "time_key": 1628057605000,
      "content_value": "zzb",
      "note1": "xxx",
      "note2": "iii",
      "note3": "qqq",
      "sys_created_time": "xxx",
      "is_deleted": true
    }
  ],
  "next_cursor": null
}

next_cursor 下页的游标，null表示无更多数据。

获取指定key的所有time

Method & Path

• POST {domain}/bp/storage/immutable/time_keys
• POST {domain}/bp/server/user/{user_id}/storage/immutable/time_keys

请求示例:

{
  "content_key": "name"
}

返回示例:

{
  "time_key_set": [
    1628057605000,
    1628057606000
  ]
}

获取指定time的数据

Method & Path

• POST {domain}/bp/storage/immutable/query/time_keys
• POST {domain}/bp/server/user/{user_id}/storage/immutable/query/time_keys

request body

参数	类型	说明
content_key	string
time_key_set	array	需要的数据集合（最多50个）

请求示例:

{
  "content_key": "name",
  "time_key_set": [
    1628057605000,
    1628057606000
  ]
}

返回示例:

{
  "immutable_storage_items": [
    {
      "user_id": "xxx",
      "content_key": "name",
      "time_key": 1628057605000,
      "content_value": "wzy",
      "note1": "xxx",
      "note2": "iii",
      "note3": "qqq",
      "sys_created_time": "xxx",
      "is_deleted": true
    }
  ]
}

删除某个用户的所有数据

Method & Path

• DELETE {domain}/bp/storage/immutable
• DELETE {domain}/bp/server/user/{user_id}/storage/immutable

返回

{}

删除某个用户的 content_key 数据

Method & Path

• DELETE {domain}/bp/storage/immutable/content_key/{content_key}
• DELETE {domain}/bp/server/user/{user_id}/storage/immutable/content_key/{content_key}

返回

{}

删除某个用户的 content_key 下 time_key 数据

Method & Path

• DELETE {domain}/bp/storage/immutable/content_key/{content_key}/{time_key}
• DELETE {domain}/bp/server/user/{user_id}/storage/immutable/content_key/{content_key}/{time_key}

返回

{}