ClassworksKV/docs/kv-token.md

KV 存储 Token API

本文档描述了基于令牌的 KV 存储 API。这些 API 端点使用应用程序安装令牌进行身份验证，而不是直接使用设备 UUID。

身份验证

所有请求都需要提供一个有效的应用程序安装令牌。令牌可以通过以下方式之一提供：

1. Authorization Header:

Authorization: Bearer YOUR_TOKEN

2. Query Parameter:

?token=YOUR_TOKEN

3. Request Body:

{
  "token": "YOUR_TOKEN"
}

API 端点

列出键名

获取命名空间下的所有键名（不包括值）。

GET /kv/token/_keys

查询参数：

• sortBy: 排序字段（默认：'key'）
• sortDir: 排序方向（'asc' 或 'desc'，默认：'asc'）
• limit: 每页记录数（默认：100）
• skip: 跳过的记录数（默认：0）

响应示例：

{
  "keys": ["key1", "key2", "key3"],
  "total_rows": 3,
  "current_page": {
    "limit": 100,
    "skip": 0,
    "count": 3
  }
}

列出所有键值对

获取命名空间下的所有键值对及其元数据。

GET /kv/token/

查询参数：

• sortBy: 排序字段（默认：'key'）
• sortDir: 排序方向（'asc' 或 'desc'，默认：'asc'）
• limit: 每页记录数（默认：100）
• skip: 跳过的记录数（默认：0）

响应示例：

{
  "items": [
    {
      "key": "key1",
      "value": { "data": "value1" },
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "total_rows": 1
}

获取单个键值

获取特定键的值。

GET /kv/token/:key

响应示例：

{
  "data": "value1"
}

获取键的元数据

获取特定键的元数据信息。

GET /kv/token/:key/metadata

响应示例：

{
  "key": "key1",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "creatorIp": "127.0.0.1"
}

批量导入

批量导入多个键值对。

POST /kv/token/_batchimport

请求体示例：

{
  "key1": { "data": "value1" },
  "key2": { "data": "value2" }
}

响应示例：

{
  "namespace": "device-uuid",
  "total": 2,
  "successful": 2,
  "failed": 0,
  "results": [
    {
      "key": "key1",
      "created": true
    },
    {
      "key": "key2",
      "created": true
    }
  ]
}

创建或更新键值

创建新的键值对或更新现有的键值对。

POST /kv/token/:key

请求体示例：

{
  "data": "value1"
}

响应示例：

{
  "namespace": "device-uuid",
  "key": "key1",
  "created": true,
  "updatedAt": "2024-01-01T00:00:00Z"
}

删除命名空间

删除整个命名空间及其所有键值对。

DELETE /kv/token/

成功时返回 204 No Content。

删除键值对

删除特定的键值对。

DELETE /kv/token/:key

成功时返回 204 No Content。

错误处理

所有错误响应都遵循以下格式：

{
  "statusCode": 400,
  "message": "错误描述"
}

常见错误代码：

• 400: 请求参数错误
• 401: 未提供令牌或令牌无效
• 403: 权限不足
• 404: 资源不存在
• 429: 请求过于频繁
• 500: 服务器内部错误

权限

API 使用以下权限系统：

• appReadAuthMiddleware: 用于读取操作
• appWriteAuthMiddleware: 用于写入操作
• appListAuthMiddleware: 用于列表操作

这些权限基于应用程序的安装记录中的 permissionPrefix 和 permissionKey 字段进行验证。