开放读写接口

引言

读写接口用于后端调用，通过 masterkey / authId&authKey 完成鉴权，masterkey 仅限于项目负责人可获取。鉴权key介绍以及获取见☞文档。

⚠️重要提示

masterkey 是一个非常重要秘钥，请保护好不泄漏给第三方，🚫禁止在前端直接使用，读写接口仅限于服务端调用。重要等级按照DB密码来对待。

读写接口也支持 authid/authkey 的鉴权方式，对应的秘钥可以在项目管理创建，实际是比 masterkey 粒度小一点的秘钥，功效一致，可以创建多个。具体调用方式请参考authId签名鉴权。

请求方式

URL 格式

• 对象接口

http://{HOST}/{API}?appid={APP_ID}&schemaid={SCHEMA_ID}&masterkey={MASTER_KEY}

• 表接口

http://{HOST}/{API}?appid={APP_ID}&masterkey={MASTER_KEY}

• 获取请求URL，示例中的URL需要替换成下图入口获得的URL。

鉴权

读写接口仅允许通过mastekey和authkey鉴权，详情请查阅☞接口鉴权秘钥/key

请求 Headers

Host: {HOST}
Content-Type: application/json; charset=UTF-8
Staffname: {userId}  (可选，如传递Staffname，会在操作日志中对审计有相关帮助，如不填，操作日志中不显示操作操作人）

请求 Body

{ "name": "foo", "desc": "平台文档", "score": 90}

注意：请求体格式为 JSON字符串，需严格按照JSON语法，仅POST/PATCH/DELETE 有效。
对于新增(POST)、修改(PATCH)请求，请求体的JSON中的每一个取值对应配置表的每一个字段。

以下示例操作的配置表字段定义如下：

字段类型	英文名(ID)	中文名
自定义ID	name	名称
文本	desc	描述
小数输入	score	评分

对象(object)

对象为配置表下的每一行数据，对象里的每个属性即为配置表的一个字段，每个对象(一行数据)必须有主键(自增ID、自定义ID)，如果没有配置ID字段，那么平台会自动添加一个默认ID。

◎ 查询列表

拉取列表数据，支持查询接口参数。### 关于数据量 接口默认获取根据创建时间正序排列的前20条（page=1&size=20&order=_ctime&desc=asc）数据，如有拉取全量数据的需求，在请求中添加size=total即可。

+ GET {HOST}/api/object 示例 （实际请求需替换为对应HOST）:

curl -X GET "http://{HOST}/api/object/?appid=demo&schemaid=demo"

响应 :

{ data: { _id: 'xxx', ... } }

tip

_id 为该对象的ID，如果没有配置ID字段，即为 默认ID(唯一字符串)

tip

query过长时 可以添加action=list到query中 同时使用POST方法发起请求 将过长的参数放入body中

处理Query超长 :

curl -X POST "http://{HOST}/api/object/?action=list"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"appid": "demo", "schemaid": "demo"}'

◎ 查询单条

根据对象ID(objectId)拉取单条数据，支持查询接口参数，:objectId 为自定义ID/自增ID/默认ID的取值。

+ GET {HOST}/api/object/:objectId

示例 （实际请求需替换为对应HOST）:

curl -X GET "http://{HOST}/api/object/12345?appid=demo&schemaid=demo"

响应 :

{ data: [{ _id: 'xxx', ... }] }

◎ 新增数据

新创建一条数据。

+ POST {HOST}/api/object

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/object?appid=demo&schemaid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"id": "12345", "name": "object 12345"}'

请求体 :

{ "name": "foo", "desc": "平台通用配置系统", "score": 99 }

响应 :

{ data: { _id: 'foo', ... } }

提示 字段name为自定义ID，取值即为对象的ID

◎ 修改数据

根据objectId(主键)修改数据。

+ POST {HOST}/api/object/patch/:objectId + PATCH {HOST}/api/object/:objectId 当objectId不存在时，接口返回错误，若指定请求参数 upsert=1，则会自动创建对象，行为等同于新建数据。【upsert=1模式，不适用联合主键】 示例 （实际请求需替换为对应HOST），例如修改 score 的值：

curl -X POST "http://{HOST}/api/object/patch/12345?appid=demo&schemaid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"score": 100 }'
  
curl -X PATCH "http://{HOST}/api/object/12345?appid=demo&schemaid=demo&upsert=1"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"score": 100 }'

请求体 : 修改时，请求体的字段可以为增量的，该操作为增量更新操作。 只提交需要更新的字段内容即可。未列出的字段不会被更新或者删除。

{ "score": 100 }

响应 :

// true: 修改成功
{ "data": true, "code": 200}
// false: 修改对象不存在
{"error":"[API.object.update(appId:demo, schemaId:demo, 12345, data)] Error: No matched rows","code":500}
// false: 修改失败其他错误
{"error":"[API.object.update(appId:demo, schemaId:demo, 12345, data)] Error: *****","code":500}

更新接口的高级用法

平台的更新接口，支持原子地更新字段数据。例如对计数器、JSON子字段进行修改。只需要在请求体里添加 Field Operator 对象即可。以下是一个例子：

{
  // 常规的更新字段值，就和上文描述一样
  "score": 100,
  
  // 同时，可以使用 $inc, $set, $push 等 Field Operator 进行原子事务更新
  "$inc": { "pageView": 1 }, // 修改字段 pageView 的数值加1
  "$mul": { "someJSON.percent": 0.9 }, // 修改JSON深层字段percent的值，乘以0.9
  "$set": { 
     "someJSON.someField": "修改JSON深层字段",
     "anotherJSON.foobar": 1234
  },
  "$unset": {
     "someJSON.fieldToDelete": true  // 从JSON里删除一个字段
  }
}

当前更新接口，支持以下 Field Operator：

操作符	适用字段类型	传入值	说明
$inc $mul $max $min	数字字段，或者 JSON里的子字段	数字	数学运算
$set	JSON里的子字段	任意值	设置JSON里的子字段（如果要修改整个字段，请不要使用 Field Operator）
$unset	JSON里的子字段	true	删除JSON里的子字段
$push	JSON里的子字段(数组)	数组，要添加的东西	向数组里添加一个或多个元
$addToSet	JSON里的子字段(数组)	数组，要添加的东西	向数组里添加 不存在的新元素（已有值不会追加）

◎ 删除数据

根据字段ID删除某条数据。

+ DELETE {HOST}/api/object/:objectId

示例 （实际请求需替换为对应HOST）:

curl -X DELETE "http://{HOST}/api/object/12345?appid=demo&schemaid=demo"

响应 :

{ data: true }

◎ 调用SQL 【仅限MySQL】

直接调用SQL，作用到对应的数据项目。注意，因SQL调用安全问题，目前仅支持authId签名一种鉴权方式。需确认你的项目挂载的DB是Mysql时才能成功调用该接口。

+ POST {HOST}/api/object/statement

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/object/statement?appid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"statement": "select * from some_schemaId" }'

◎ 导出到Excel文件

拉取指定表的数据并生成文件响应。支持传入👉🏻查询参数 。支持生成的文件格式见 👉🏻此文档，默认为 xlsx。

+ POST {HOST}/api/object/excel

示例:

# 此 curl 仅做接口协议展示用途，如需储存文件请自行处理, 例如 fs.writeFileSync。
curl -X POST \   
    'http://{HOST}/api/object/excel?appid={appId}&schemaid={schemaId}&masterkey={masterkey}&size=total&page=1&datetime=timestamp' \
    -H 'Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' \
    -d '{"bookType": "xlsx"}'

如需文件流，请在 body 中增加 "stream": true

表(schema)

◎ 查询列表

拉取多个表（数据表列表）的信息，支持查询接口参数，

+ GET {HOST}/api/schema

响应 :

{ data: { id: 'xxx', ... } }

◎ 查询单条

拉取单个表信息，支持查询接口参数

+ GET {HOST}/api/schema/:schemaId

示例 （实际请求需替换为对应HOST）:

curl -X GET "http://{HOST}/api/schema/schema123?appid=demo"

响应 :

{ data: [{ id: 'xxx', ... }] }

◎ 新增表

创建一张数据表。

+ POST {HOST}/api/schema

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/schema?appid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"id": "schema123", "name": "schema demo 123"}'

请求体 :

{
  "id: "",             
  "name": "",           
  "desc": "",           
  "creator": [""],      
  "participant": [""],
  fields: [...],
}

响应 :

{ data: [{ id: 'xxx', ... }] }

常见QA:

• 表字段fields的协议是怎样的？ 平台支持的字段类型多种，每个类型的配置不太一样，建议在平台表配置页，添加你想通过接口创建的字段类型，通过抓包 /schema (关键字)，就可以了解每个字段的具体配置。

◎ 修改表

增量修改数据表信息。

+ PATCH {HOST}/api/schema/:schemaId

示例 （实际请求需替换为对应HOST）:

curl -X PATCH "http://{HOST}/api/schema/schema123?appid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"name": "schema demo 123"}'

请求体 :

{
  "id: "",             
  "name": "",           
  "desc": "",           
  "creator": [""],      
  "participant": [""],
  fields: [...],
}

响应 :

{ data: true }

◎ 删除表

根据 schemaId 删除数据表。

+ DELETE {HOST}/api/schema/:schemaId

示例 （实际请求需替换为对应HOST）:

curl -X DELETE "http://{HOST}/api/schema/schema123?appid=demo"

响应 :

{ data: true }

行版本

◎ 开启行版本

将表的版本管理模式改为“行版本”

+ POST {HOST}/api/schema/path/:schemaId

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/schema/patch/main?appid=demo"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"versioning": "line"}'

请求体 :

{
  "versioning": "line"
}

◎ 查询数据的发布状态

检查指定数据是否已经发布

+ POST {HOST}/api/lv/check?appid={APP_ID}&schemaid={SCHEMA_ID}

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/lv/check?appid=xxx&schemaid=xxxx"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"ids":["6102154adcbeba0181665b4f","6102167773fabbbd459da3e4"]}'

请求体 :

{
  "ids": [
    "6102154adcbeba0181665b4f",
    "6102167773fabbbd459da3e4"
  ]
}

响应：

{
    "data": [{
        id: "6102154adcbeba0181665b4f",
        status: 2, // 0: 数据不存在, 1: 已发布 2: 未发布
    }, {
        id: "6102167773fabbbd459da3e4",
        status: 1,
    }]
}

◎ 全量发布

将指定的数据发布到线上

+ POST {HOST}/api/lv/publish/:dataId?appid={APP_ID}&schemaid={SCHEMA_ID}

示例 （实际请求需替换为对应HOST）:

curl -X POST "http://{HOST}/api/lv/publish/6102154adcbeba0181665b4f?_appid=vvdenniswu&_schemaid=main"
  -H "Content-Type: application/json; charset=UTF-8"
  -d '{"desc": "修改数据:6102154adcbeba0181665b4f,更新字段:test,_mtime"}'

请求体 :

{
  "desc": "修改数据:6102154adcbeba0181665b4f,更新字段:test,_mtime"
}

target	action
object	create
	delete
	update
	rollback:create
	rollback:delete
	rollback:update
version	create
	delete
	release
	grayRelease
	takedownGrayRelease
schema	create
	delete
	update