数据操作

获得数据表数据接口,支持对内置表自定义字段的获取与修改

查询数据

接口

GET https://cloud.minapp.com/userve/v1/table/:table_id/record/

其中 :table_id 需替换为你的数据表 ID

参数说明

Content-Type: application/json

参数类型必填说明
whereStringN查询语句,参数值应经过 JSON 编码为 JSONString 后,再经过 URL 编码
order_byStringN对资源进行字段排序
limitNumberN限制返回资源的个数,默认为 20 条,最大可设置为 1000
offsetNumberN设置返回资源的起始偏移值,默认为 0

例如需要查询价格为 10 元的物品时,我们应该这样构造查询语句:

  1. {
  2. "price": {"$eq": 10}
  3. }

执行

  1. var axios = require('axios').create({
  2. withCredentials: true
  3. })
  4. axios.get('https://cloud.minapp.com/userve/v1/table/1/record/', {params: {where: {price: {$eq: 10}}}}).then(res => {
  5. console.log(res.data)
  6. })

该接口完整支持的查询操作符如下:

查询操作符含义
$eq等于
$ne不等于
$lt小于
$lte小于等于
$gt大于
$gte大于等于
$contains包含任意一个值
$nin不包含任意一个数组值
$in包含任意一个数组值
$isnull是否为 NULL
$range包含数组值区间的值

使用以上查询操作符即可完成一些简单的条件查询,同时,你也可以使用 $and$or 查询操作符,对以上查询操作符进行组合使用,完成更复杂的条件查询,如查询 价格为 10 元且产品名称中包含 “包” 的物品价格大于 100 元的物品,其筛选条件为:

  1. {
  2. "$or": [
  3. {
  4. "$and": [
  5. {
  6. "price": {"$eq": 10}
  7. },
  8. {
  9. "name": {"$contains": "包"}
  10. }
  11. ]
  12. },
  13. {
  14. "price": {"$gt": 100}
  15. }
  16. ]
  17. }

排序返回查询数据

查询接口默认按创建时间倒序的顺序来返回数据列表,你也可以通过设置 order_by 参数来实现。

示例:

  1. # 顺序
  2. https://cloud.minapp.com/userve/v1/table/:table_id/record/?order_by=created_at
  3. # 倒序
  4. https://cloud.minapp.com/userve/v1/table/:table_id/record/?order_by=-created_at

获取数据项

接口

GET https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/

其中 :table_id 需替换为你的数据表 ID,record_id 需替换为你的记录 ID

写入数据

接口

POST https://cloud.minapp.com/userve/v1/table/:table_id/record/

其中 :table_id 需替换为你的数据表 ID

参数说明

Content-Type: application/json

参数类型必填说明
keykey 字段对应的数据类型Ykey 应为数据表中定义的字段名

插入的数据要与预先在知晓云平台设定的数据类型一致

状态码说明

201 写入成功,400 请求参数有错

更新数据

本接口提供数据更新的能力,通过指定表 ID 以及 Record ID 来完成操作, 需注意,更新的数据所包含的字段需要与数据表中定义的字段一致。

接口

PUT https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/

其中 :table_id 需替换为你的数据表 ID,record_id 需替换为你的记录 ID

参数说明

Content-Type: application/json

参数类型必填说明
keykey 字段对应的数据类型Ykey 应为数据表中定义的字段名

更新的数据要与预先在知晓云平台设定的数据类型一致

状态码说明

201 写入成功,400 请求参数有错

数据删除

本接口可直接删除任意数据,不受 ACL 控制

接口

DELETE https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/

其中 :table_id 需替换为你的数据表 ID,record_id 需替换为你的记录 ID

状态码说明

204 删除成功

数据原子性更新

当请求同时对一个数据进行修改时,原子性更新使得冲突和覆盖导致的数据不正确的情况不会出现,目前支持的数据类型是数字类型数组类型

接口

PUT https://cloud.minapp.com/userve/v1/table/:table_id/record/:record_id/

其中 :table_id 需替换为你的数据表 ID,record_id 需替换为你的记录 ID

参数说明

Content-Type: application/json

参数类型必填说明
keykey 字段对应的数据类型Ykey 应为数据表中定义的字段名

本接口支持以下原子性操作:

(1) incr_by 对数字类型的字段的值进行增减操作

将对象中的价格(price)字段加 1

  1. {
  2. "price": {
  3. "$incr_by": 1
  4. }
  5. }

将对象中的价格(price)字段减 1

  1. {
  2. "price": {
  3. "$incr_by": -1
  4. }
  5. }

(2) append 对数组类型的字段的值追加一个数组

往对象中的 tag 字段追加 「Hello」

  1. {
  2. "tag": {
  3. "$append": ["Hello"]
  4. }
  5. }

(3) append_unique 对数组类型的字段的值追加一个数组,但追加的数组里的数组项,如果已存在于原数组中,则该数组项不会再被追加

往对象中的 tag 字段追加 「Hello」,tag 字段依然为 ["Hello"]

  1. {
  2. "tag": {
  3. "$append_unique": ["Hello"]
  4. }
  5. }

(4) remove 从数组类型的字段的值里,删除包含在指定数组中的数组项

往对象中的 tag 字段删除 「Hello」

  1. {
  2. "tag": {
  3. "$remove": ["Hello"]
  4. }
  5. }

状态码说明

200 更新成功,400 操作符不支持/请求参数有错

以下操作仅适用于 API version >= v1.8

pointer 查询

目前 pointer 仅支持针对 pointer 本身的查询,不支持嵌套查询(即查询 pointer 指向的数据行的字段)

接口

GET https://cloud.minapp.com/userve/v1.8/table/:table_id/record/?where=query

其中 :table_id 需替换为你的数据表 ID,query 为查询条件

示例代码

假设现在有两张表: order 表和 customer 表,order 表中有一个类型为 pointer,名称为 user 的字段,指向了 customer 表的数据行。现在需要查询 order 表中,user 字段指向 customer 表中 id 为 5bf4f7457fed8d6c2f5c3d6e 的数据行。

  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/userve/v1.8/table/3906/record/', // 3906 对应 :table_id
  4. method: 'GET',
  5. headers: {
  6. Authorization: `Bearer ${token}`,
  7. },
  8. qs: { // query string, 被附加到uri的参数
  9. where: JSON.stringify({ // 可选, 参数值应经过 JSON 编码为 JSONString 后,再经过 URL 编码
  10. "user": {"$eq": "5bf4f7457fed8d6c2f5c3d6e"}
  11. }),
  12. order_by: 'id', // 可选
  13. offset: 0, // 可选
  14. limit: 20, // 可选
  15. }
  16. }
  17. request(opt, function(err, res, body) {
  18. console.log(body)
  19. })
  1. import json
  2. import urllib
  3. import requests
  4. table_id = ''
  5. BASE_API = r'https://cloud.minapp.com/userve/v1.8/table/%s/record/' % table_id
  6. TOKEN = ''
  7. HEADERS = {
  8. 'Authorization': 'Bearer %s' % TOKEN
  9. }
  10. where_ = {
  11. 'user': {'$eq': "5bf4f7457fed8d6c2f5c3d6e"},
  12. }
  13. query_ = urllib.urlencode({
  14. 'where': json.dumps(where_),
  15. 'order_by': '-id',
  16. 'limit': 10,
  17. 'offset': 0,
  18. })
  19. API = '?'.join((BASE_API, query_))
  20. resp_ = requests.get(API, headers=HEADERS)
  21. print resp_.content
  1. <?php
  2. $table_id = 1; // 数据表 ID
  3. $condition = array(
  4. 'order_by' => '-id',
  5. 'where' => json_encode(['user' => ['$eq' => '5bf4f7457fed8d6c2f5c3d6e']]),
  6. 'limit' => '10',
  7. 'offset' => '0',
  8. );
  9. $url = "https://cloud.minapp.com/userve/v1.8/table/{$table_id}/record/?";
  10. $url .= http_build_query($condition);
  11. $ch = curl_init();
  12. $header = array(
  13. "Authorization: Bearer {$token}",
  14. 'Content-Type: application/json; charset=utf-8',
  15. );
  16. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  17. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  18. curl_setopt($ch, CURLOPT_URL, $url);
  19. curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  20. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  21. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  22. $res = curl_exec($ch);
  23. curl_close($ch);

字段扩展

支持 expand created_by 以及 pointer 类型字段。返回结果中的 created_by 以及扩展的 pointer 类型字段会被替换为这个字段对应的完整对象。

接口

GET https://cloud.minapp.com/userve/v1.8/table/:table_id/record/?expand=pointer,created_by

其中 :table_id 需替换为你的数据表 ID

expand 返回结果示例

不使用 expand

  1. {
  2. "created_at": 1516118400,
  3. "created_by": 1234,
  4. "id": "5a2fa9b008443e59e0e67829",
  5. "name": "小米无线耳机",
  6. "price": 199,
  7. "pointer": {"id": "5a2fa9b008443e59e0e67889", "_table": "pointer"}
  8. }

使用 expand

  1. {
  2. "created_at": 1516118400,
  3. "created_by": {
  4. "avatar": "https://media.ifanrusercontent.com/tavatar/fb/cd/xxxx.jpg",
  5. "id": 62536607,
  6. "nickname": "Larry。"
  7. },
  8. "id": "5a2fa9b008443e59e0e67829",
  9. "name": "小米无线耳机",
  10. "price": 199,
  11. "pointer": {
  12. "id": "5a2fa9b008443e59e0e67889",
  13. "_table": "pointer",
  14. "customized_field": "field_content"
  15. }
  16. }

代码示例

  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/userve/v1.8/table/3906/record/', // 3906 对应 :table_id
  4. method: 'GET',
  5. headers: {
  6. Authorization: `Bearer ${token}`,
  7. },
  8. qs: { // query string, 被附加到uri的参数
  9. where: JSON.stringify({ // 可选, 参数值应经过 JSON 编码为 JSONString 后,再经过 URL 编码
  10. "price": {"$eq": 10}
  11. }),
  12. order_by: 'id', // 可选
  13. offset: 0, // 可选
  14. limit: 20, // 可选
  15. expand: 'pointer,created_by', //必选,表示需要扩展的字段
  16. }
  17. }
  18. request(opt, function(err, res, body) {
  19. console.log(body)
  20. })
  1. import json
  2. import urllib
  3. import requests
  4. table_id = ''
  5. BASE_API = r'https://cloud.minapp.com/userve/v1.8/table/%s/record/' % table_id
  6. TOKEN = ''
  7. HEADERS = {
  8. 'Authorization': 'Bearer %s' % TOKEN
  9. }
  10. where_ = {
  11. 'price': {'$gt': 100},
  12. }
  13. query_ = urllib.urlencode({
  14. 'where': json.dumps(where_),
  15. 'order_by': '-id',
  16. 'limit': 10,
  17. 'offset': 0,
  18. 'expand': 'pointer,created_by'
  19. })
  20. API = '?'.join((BASE_API, query_))
  21. resp_ = requests.get(API, headers=HEADERS)
  22. print resp_.content
  1. <?php
  2. $table_id = 1; // 数据表 ID
  3. $condition = array(
  4. 'order_by' => '-id',
  5. 'where' => json_encode(['price' => ['$gt' => 'test search']]),
  6. 'limit' => '10',
  7. 'offset' => '0',
  8. 'expand' => 'pointer,created_by'
  9. );
  10. $url = "https://cloud.minapp.com/userve/v1.8/table/{$table_id}/record/?";
  11. $url .= http_build_query($condition);
  12. $ch = curl_init();
  13. $header = array(
  14. "Authorization: Bearer {$token}",
  15. 'Content-Type: application/json; charset=utf-8',
  16. );
  17. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  18. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  19. curl_setopt($ch, CURLOPT_URL, $url);
  20. curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
  21. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  22. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  23. $res = curl_exec($ch);
  24. curl_close($ch);

添加 pointer 类型数据

接口

POST https://cloud.minapp.com/userve/v1.8/table/:table_id/record/

其中 :table_id 需替换为你的数据表 ID

代码示例

  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/userve/v1.8/table/3906/record/', // 3906 对应 :table_id
  4. method: 'POST',
  5. headers: {
  6. Authorization: `Bearer ${token}`,
  7. },
  8. json: { // 指定 data 以 "Content-Type": 'application/json' 传送
  9. name: 'nickname',
  10. desc: ['description'],
  11. price: 19,
  12. amount: 19,
  13. code: '18814098707'
  14. pointer: '5a2fa9b008443e59e0e67889', // pointer 关联的数据 ID
  15. }
  16. }
  17. request(opt, function(err, res, body) {
  18. console.log(res.statusCode)
  19. })
  1. <?php
  2. $table_id = 1;
  3. $param = array(
  4. 'pointer' => '5a2fa9b008443e59e0e67889'
  5. );
  6. $url = "https://cloud.minapp.com/userve/v1.8/table/{$table_id}/record/";
  7. $ch = curl_init();
  8. $header = array(
  9. "Authorization: Bearer {$token}",
  10. 'Content-Type: application/json; charset=utf-8',
  11. );
  12. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  13. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  14. curl_setopt($ch, CURLOPT_URL, $url);
  15. curl_setopt($ch, CURLOPT_POST, true);
  16. curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($param));
  17. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  18. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  19. $res['response'] = curl_exec($ch); // 反馈结果
  20. $res['status_code'] = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 请求状态码
  21. curl_close($ch);

状态码说明

201 写入成功,400 请求参数有错

更新 pointer 类型数据

接口

PUT https://cloud.minapp.com/userve/v1.8/table/:table_id/record/:record_id/

其中 :table_id 需替换为你的数据表 ID,record_id 需替换为你的记录 ID

代码示例

  1. var request = require('request');
  2. var opt = {
  3. uri: 'https://cloud.minapp.com/userve/v1.8/table/3906/record/5a6ee2ab4a7baa1fc083e3xx', // 3906 对应 :table_id, 5a6ee2ab4a7baa1fc083e3xx 对应 :record_id
  4. method: 'PUT',
  5. headers: {
  6. Authorization: `Bearer ${token}`,
  7. },
  8. json: { // 指定 data 以 "Content-Type": 'application/json' 传送
  9. pointer: '5a2fa9b008443e59e0e67889', // pointer 关联的数据 ID
  10. }
  11. }
  12. request(opt, function(err, res, body) {
  13. console.log(res.statusCode)
  14. })
  1. <?php
  2. $table_id = 1; // 数据表 ID
  3. $record_id = '5a6ee2ab4a7baa1fc083e3xx'; // 记录 ID
  4. $url = "https://cloud.minapp.com/userve/v1.8/table/{$table_id}/record/{$record_id}/";
  5. $param['pointer'] = '5a2fa9b008443e59e0e67889';
  6. $ch = curl_init();
  7. $header = array(
  8. "Authorization: Bearer {$token}",
  9. 'Content-Type: application/json; charset=utf-8'
  10. );
  11. curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
  12. curl_setopt($ch, CURLOPT_TIMEOUT, 30);
  13. curl_setopt($ch, CURLOPT_URL, $url);
  14. curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PUT');
  15. curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($param));
  16. curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  17. curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, true);
  18. $res['response'] = curl_exec($ch); // 反馈结果
  19. $res['status_code'] = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 请求状态码
  20. curl_close($ch);

状态码说明

200 更新成功,400 请求参数有错