存储队列 API 接入文档
华网科技 ∙ hwwlyz.com2026/05/26
华网网络验证提供了存储分发队列系统，支持数据的存储、提取、删除与批量下载，适用于数据中转、任务队列、消息分发等场景。
接入须知
使用方式
所有接口需要在请求中携带密钥 password，可通过以下任一方式传递：
- URL Query 参数：
?password=xxx - Request Body 字段：
{"password": "xxx"} - HTTP Header：
X-Api-Password: xxx
接口基础地址：
http://<host>/api/:key
其中 :key 为你的存储队列唯一标识（由系统分配）。
通用说明
认证方式
| 方式 | 示例 |
|---|---|
| Query 参数 | ?password=my_secret_key |
| Body 字段 | {"password": "my_secret_key", ...} |
| Header | X-Api-Password: my_secret_key |
响应格式
所有接口统一返回 JSON 格式：
{
"code": 0,
"message": "success",
"data": {}
}
获取数据
获取指定数量的队列数据。支持两种模式：只读读取（不删除）和即取即删。
语法
GET /api/:key?password=xxx
参数
| 参数名 | 必传 | 类型 | 默认值 | 说明 |
|---|---|---|---|---|
| password | 是 | string | - | 接口密钥 |
| count | 否 | number | - | 取 N 条数据（只读模式，随机/前N条） |
| start | 否 | number | - | 范围读取起始下标（不去重模式） |
| stop | 否 | number | - | 范围读取结束下标（不去重模式） |
TIP
模式说明
- 即取即删模式：不传 count/start/stop 参数时生效，获取一条数据并立即从队列中删除
- 只读模式：传
count参数时生效，获取 N 条数据但不会删除 - 范围模式：传
start+stop时生效，获取指定范围内的数据（不去重、不删除）
请求示例
# 取 3 条数据（只读）
curl "http://host/api/mykey?password=xxx&count=3"
# 不去重模式范围取 0-10 条
curl "http://host/api/mykey?password=xxx&start=0&stop=10"
返回值
{
"code": 0,
"message": "success",
"data": ["data1", "data2", "data3"]
}
上传数据
批量上传多条数据到队列尾部。
语法
POST /api/:key?password=xxx
参数
| 参数名 | 必传 | 类型 | 说明 |
|---|---|---|---|
| password | 是 | string | 接口密钥 |
| lines | 是 | string[] | 数据行数组，例：["data1","data2"] |
请求示例
curl -X POST "http://host/api/mykey?password=xxx" \
-H "Content-Type: application/json" \
-d '{"lines":["data1","data2"]}'
返回值
{
"code": 0,
"message": "success",
"data": {
"inserted": 2
}
}
上传单条数据
上传单条数据到队列尾部。
语法
POST /api/:key/uploadOne?password=xxx
参数
| 参数名 | 必传 | 类型 | 说明 |
|---|---|---|---|
| password | 是 | string | 接口密钥 |
| line | 是 | string | 单条数据内容 |
请求示例
curl -X POST "http://host/api/mykey/uploadOne?password=xxx" \
-H "Content-Type: application/json" \
-d '{"line":"data1"}'
返回值
{
"code": 0,
"message": "success",
"data": {
"inserted": 1
}
}
删除数据
删除队列中指定的一条数据。
语法
DELETE /api/:key?password=xxx
参数
| 参数名 | 必传 | 类型 | 说明 |
|---|---|---|---|
| password | 是 | string | 接口密钥 |
| value | 是 | string | 要删除的数据内容 |
请求示例
curl -X DELETE "http://host/api/mykey?password=xxx" \
-H "Content-Type: application/json" \
-d '{"value":"data1"}'
返回值
{
"code": 0,
"message": "success"
}
兼容接口
同时也支持 POST 方式调用删除接口：
POST /api/:key/delete?password=xxx
curl -X POST "http://host/api/mykey/delete?password=xxx" \
-H "Content-Type: application/json" \
-d '{"value":"data1"}'
下载全部数据
以文本文件形式下载队列中的所有数据，每行一条。
语法
GET /api/:key/download?password=xxx
参数
| 参数名 | 必传 | 类型 | 说明 |
|---|---|---|---|
| password | 是 | string | 接口密钥 |
请求示例
curl -OJ "http://host/api/mykey/download?password=xxx"
返回值
返回 Content-Disposition: attachment 的文本文件（.txt），每行一条数据记录。
data1
data2
data3
查看套餐信息
返回当前队列的配额、速率限制、提取模式等配置信息。
语法
GET /api/:key/plan?password=xxx
参数
| 参数名 | 必传 | 类型 | 说明 |
|---|---|---|---|
| password | 是 | string | 接口密钥 |
请求示例
curl "http://host/api/mykey/plan?password=xxx"
返回值
{
"code": 0,
"message": "success",
"data": {
"totalQuota": 10000,
"usedQuota": 2340,
"rateLimit": 100,
"mode": "fifo",
"expires": "2026-06-26 00:00:00"
}
}
接口速查
| 接口 | 方法 | 路径 | 功能 |
|---|---|---|---|
| 获取数据 | GET | /api/:key | 获取队列数据（支持只读/即取即删） |
| 上传数据 | POST | /api/:key | 批量上传多条数据 |
| 上传单条 | POST | /api/:key/uploadOne | 上传单条数据 |
| 删除数据 | DELETE | /api/:key | 删除指定数据 |
| 删除数据(兼容) | POST | /api/:key/delete | 删除指定数据（POST 方式） |
| 下载全部 | GET | /api/:key/download | 下载全部数据为文本文件 |
| 套餐信息 | GET | /api/:key/plan | 查看配額与配置信息 |
如有问题或建议，欢迎反馈！
Powered by Waline v2.14.7