pub_soft/BaiduPCS-Go
3
0
Fork 0
mirror of https://github.com/qjfoidnh/BaiduPCS-Go.git synced 2026-06-04 18:04:24 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
dev
BaiduPCS-Go/docs/structured_data_api_list.md
qjfoidnh 70fe168f0f Update README.md
2020-11-07 02:28:22 +08:00

106 KiB
Raw Permalink Blame History

结构化数据API列表

更新通知：

2013.7.2 修改“创建table”接口，请求参数增加“sk”

创建table

功能

创建一个表，定义索引，其中包括对唯一索引的支持。

注意：

  • 一个应用最多创建5个表，一个表上最多创建5个索引；

  • 关于表和索引的创建规则，您可以参考“结构化数据表基本概念”；

  • 为保证一致性，创建表后，可能需要等待一段时间才能用describe table接口查看到；

  • 创建一张表必须带有该表所属app的密匙sk，用于之后的psstoken鉴权使用。

关于“唯一索引”的说明：

  • 可以建联合的唯一索引；

  • 一个table上唯一索引数量同一般索引限制，5个；

  • 唯一索引不支持在表创建后在增加，所以需要在表设计的时候尽量考虑；（如确实需要，可联系我们。）

  • insert的时候必须带上唯一索引的所有字段，否则会失败。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/table

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：create。
access_token string 是 开发者的应用所对应的access_token。
table string 是 表名。
sk string 是 该表所属app的密匙（secret key），用于psstoken鉴权使用。
column json 否 列描述。
index json 否 索引描述：

  • 1：表示升序索引

  • -1：表示降序索引

返回参数

参数名称 类型 描述
error_code number 错误码, 如果不出错, 则返回值没有该字段。
error_msg string 错误提示, 如果不出错, 则返回值没有该字段。
app_id int 应用对应的ID。
table string 表名。
request_id int 请求ID号。

示例

请求示例:

1. 创建一般索引

$ cat > ./artists_create_table <<DELIM
{
    "table" : "artists",
    "column" :
    {
        "id" :
        {
            "description" : "",
            "type" : "int",
            "required" : true
        }
    },
    "index":
    {
        "id_index" :
        {
            "column" : {"id" : 1}
        }
    }
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=create&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347&sk=cRgk8uMGX098yMfmttoVYswcv3XKBLGX" -F "param=<artists_create_table"

2. 创建唯一索引

$ cat > ./artists_create_table <<DELIM
{
    "table" : "artists",
    "column" :
    {
        "id" :
        {
            "description" : "",
            "type" : "int",
            "required" : true
        }
    },
    "index":
    {
        "id_index" :
        {
            "column" : {"id" : 1},
            "unique" : true
        }
    }
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=create&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347&sk=cRgk8uMGX098yMfmttoVYswcv3XKBLGX " -F "param=<artists_create_table"

注意

unique字段为true，表示唯一索引；为false，则表示一般索引；不指定则默认为一般索引。

正确响应示例：

HTTP/1.1 200 OK
 
{
"app_id" : 1,
"table" : "artists",
"request_id" : 3728395580
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code" : 31472,
"error_msg" : "table already exist",
"request_id" : 9085631045
}

修改table

功能

修改一个表，添加或者删除索引

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/table

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：alter。
access_token string 是 开发者的access_token。
table string 是 表名。
add_index json 否 增加的索引。
drop_index json 否 删除的索引。

返回参数

参数名称 类型 描述
error_code number 错误码，如果不出错，则返回值没有该字段。
error_msg string 错误提示，如果不出错，则返回值没有该字段。
appid int 开发者App ID。
table string 表名。
column json 列描述。
index json 索引描述：

  • 1：表示升序索引；

  • -1：表示降序索引。

示例

请求示例: 

$ cat > ./artists_alter_table <<DELIM
{
"table" : "artists",
"add_index" :
{
"direction" :
{
"column" : {"direction" : 1}
}
},
"drop_index":
{
"id_index" :
{
"column" : {"id" : 1}
}
}
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=alter&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_alter_table"
 
正确响应示例：
HTTP/1.1 200 OK
 
{
"app_id" : 1,
"table" : "artists",
"lastindex" :
{
"direction" :
{
"column" :
{
"direction" : 1
}
}
},
"request_id" : 6402295586
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code" : 31409,
"error_msg" : "table not exist",
"request_id" : 9360693908
}

删除table

功能

删除一个table

注意

如果drop到回收站（默认情况），则drop后该表处于不可访问状态，不能再创建同名的table。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/table

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：drop。
access_token string 是 开发者的App对应的access_token。
table string 是 表名。
op string 否 值为recycled: drop到回收站，可用restore接口恢复。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
app_id int App对应的ID。
table string 表名。
request_id int 请求ID号。

示例

请求示例: 

 $ cat > ./artists_drop_table <<DELIM
{
"table" : "artists"
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=drop&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_drop_table"
正确响应示例：
HTTP/1.1 200 OK
 
{
"app_id" : 1,
"table" : "artists",
"request_id" : 3728395580
}
 
</pre>
出错响应示例：<javascript>HTTP/1.1 400 Bad Request
 
{
"error_code" : 31409,
"error_msg" : "table not exist",
"request_id" : 9085631045
}

从回收站恢复table

功能

恢复一个在回收站中的表。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/table

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：restore。
access_token string 是 开发者的App对应的access_token。
table string 是 表名。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
app_id int App对应的ID。
table string 表名。
request_id int 请求ID号。

示例

请求示例: 

$ cat > ./artists_restore_table <<DELIM
{
"table" : "artists"
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=restore&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_restore_table"
 
正确响应示例：
HTTP/1.1 200 OK
{
"app_id" : 1,
"table" : "artists",
"request_id" : 3728395580
}
出错响应示例：
HTTP/1.1 400 Bad Request
{
"error_code" : 31474,
"error_msg" : "table not drop, cannot restore",
"request_id" : 9085631045
}

查看table创建信息

功能

查看一个表的创建信息。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/table

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号， 默认为“1.0”。
method string 是 固定值：describe。
access_token string 是 开发者的App对应的access_token。
table string 是 表名。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
app_id int App对应的ID。
table string 表名。
request_id int 请求ID号。
column json 表的列描述。
index json 表的索引描述。
quota int 该表单个用户最大的条目数限制。
auth_code string 第三方应用请忽略此参数。

示例

请求示例: 

 $ cat > ./artists_describe_table <<DELIM
{
"table" : "artists"
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/table?method=describe&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_describe_table"
正确响应示例：
HTTP/1.1 200 OK
{
"appid" : 1,
"table" : "artists008",
"status" : 0,
"ctime" : 1347417209,
"mtime" : 1347417209,
"cluster" : "cluster0",
"subtablenum" : 1,
"column" :
{
"id" :
{
"description" : "",
"type" : "number",
"required" : true
}
},
"index":
{
"id_index" :
{
"column" : {"id" : 1}
}
},
"quota" : 10000,
"auth_code" : "e3725dd9a7cbd0a5e3eb7928ab922d33",
"request_id" : 2707788940
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code" : 31409,
"error_msg" : "table not exist",
"request_id" : 5574355722
}

添加record

功能

新增record，每次调用都会新增传入的record。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：insert。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 要插入的目标表名。
records json array 是 需要插入的record JSON对象构成的数组。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
records json array 返回服务器端已经处理的records(_key, _mtime, _ctime)列表，顺序与输入顺序一致；如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已处理成功的key。

示例

请求示例:

cat > ./artists_insert_request <<DELIM
{
    "table":"artists",
    "records": [
        {
            "id": 85617,
            "name": "刘德华",
            "type": "男歌手",
            "intro": "香港著名歌手、演员",
            "add_time": 1340949289,
            "language": ["国语", "粤语"],
            "tags": ["香港电影金像奖", "四大天王", "东亚唱片"],
            "top_song": {
                "id": 3, 
                "name": "爱你一万年"
            }
        },
        {
            "id": 85618,
            "name": "凤凰传奇",
            "type": "组合",
            "intro": "中国大陆具有广泛知名度的男女二人音乐组合",
            "add_time": 1340949289,
            "language": ["国语"],
            "tags": ["月亮之上", "最炫民族风"],
            "top_song": {
                "id": 5, 
                "name": "月亮之上"
            }
         }
    ]
}
DELIM
 
$ curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=insert&access_token=2.b06c3e86610fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_select1_request"

正确响应示例：

HTTP/1.1 200 OK
 
{
"records":[
{
"_key":"f44603de003c57d5-1346066442",
"_mtime":1346066442,
"_ctime":1346066442
},
{
"_key":"1aaef0010c012db7-1346066442",
"_mtime":1346066442,
"_ctime":1346066442
}
],
"request_id":3728395580
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code":31430,
"error_msg":"bad record",
"request_id":0
"records": [
{"_key": "7d4febca4a68e763-1344915172"},
]
}

更新record

功能

根据_key更新record；支持批量更新，但只能更新非回收站的record。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否

必需

描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：update。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 要更新的目标表名。
records json array 是 需要更新的record。
op string 否

  • 当值为“merge”时，请求中record不带的column，保持旧值（默认值）；

  • 当值为“replace”时，参数中传的record将全量替换整个旧的record。

说明：

其中records是一个数组，其数组成员结构如下：

名称 类型 是否必需 描述
record json 是 需要更新的record，只能是一个record，并且必须指定_key。
if-match string 否 条件更新，防止写操作覆盖了其它client的数据值；为上次获取该item时返回的_mtime属性，只有server端保存的_mtime和用户携带的_mtime一致时，才会进行更新操作。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
records json array 返回服务器端已经处理的records(_key, _mtime)列表，顺序与输入顺序一致；如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已经处理成功的key。

示例

请求示例: 

$ cat > ./artists_update_request <<DELIM
{
"table":"artists",
"records": [
{
"record":
{
"_key":"f44603de003c57d5-1346066442",
"id": 85617,
"name": "刘德华",
"type": "男歌手",
"intro": "香港著名歌手、演员",
"add_time": 1340949289,
"language": ["国语", "粤语"],
"tags": ["香港电影金像奖", "四大天王", "东亚唱片"]
},
"if-match": 1346066442
},
{
"record":
{
"_key":"1aaef0010c012db7-1346066442",
"id": 85618,
"name": "凤凰传奇",
"type": "组合",
"intro": "中国大陆具有广泛知名度的男女二人音乐组合",
"add_time": 1340949289,
"language": ["国语"],
"tags": ["月亮之上", "最炫民族风"]
},
"if-match": 1346066442
}
]
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/data?method=update&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_update_request"
 
正确响应示例：
HTTP/1.1 200 OK
 
{
"records":[
{
"_key":"f44603de003c57d5-1346066442",
"_mtime":1346066823
},
{
"_key":"1aaef0010c012db7-1346066442",
"_mtime":1346066824
}
],
"request_id":9201162933
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code":31430,
"error_msg":"bad record",
"request_id":0
"records": [
]
}

删除record

功能

根据_key，删除record。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：delete。
access_token string 是 用户access_token，HTTPS调用时必须使用。
table string 是 要删除的目标表名。
records json array 是 需要删除的record _key 数组。
op string 否

  • 当值为“permanent”时，永久删除record；无论是普通record还是回收record。

  • 当值为“recycled”时，将普通record放进回收站；缺省情况为放进回收站。

说明：

其中records是一个数组，其数组成员结构如下：

名称 类型 是否必需 描述
_key string 是 需要更新的record _key字段的值。
if-match string 否 类似update中的条件更新值为上次获取该item时返回的_mtime属性；只有server端保存的_mtime和用户携带的_mtime一致时，才会发生delete。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误消息。如果不出错，则返回值没有该字段。
records json array 返回服务器端已经处理的records(_key, _mtime)列表，顺序与输入顺序一致，如果一个请求包含多个record，遇到第一个出错record即中止，返回的records 只包含已经处理成功的key。

示例

请求示例: 

$ cat > ./artists_delete_request <<DELIM
{
"table":"artists",
"records": [
{
"_key": "f44603de003c57d5-1346066442",
"if-match": 1346066823
}
]
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/data?method=delete&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_delete_request"
 
正确响应示例：
HTTP/1.1 200 OK
 
{
"records":[
{
"_key":"f44603de003c57d5-1346066442",
"_mtime":1346066823
}
],
"request_id":9494352006
}
出错响应示例：
HTTP/1.1 400 Bad Request
 
{
"error_code":31430,
"error_msg":"bad record",
"request_id":0
"records": [
{"_key": "7d4febca4a68e763-1344915172"},
]
}

查询record

功能

通过一定条件查询record，只能select非回收站的record。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：select。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 查询的目标表名。
condition json 是 查询条件，参见查询条件描述。
projection array 否 指定需要哪些字段，_key为默认返回值。
order_by array 否 排序字段。
start number 否 分页用，默认为“0”，范围要求>=0。
limit number 否 分页用，默认为“100”，范围要求[1, 10000]。

所支持的查询条件如下表所示：

查询条件 类型 表达查询条件 示例
'=' number/string 表示范围查询= "name": {"=": "刘德华"}
'<' number/string 表示范围查询<
'>' number/string 表示范围查询> "add_time": {">": 1340949589}
'<=' number/string 表示范围查询<=
'>=' number/string 表示范围查询>= "add_time": {">=": 1340949589}
'!= ' number/string 不等于 "add_time": {"!=": 1340949589} (coming soon)
'like' string SQL中like语法(不区分大小写) * 表示0到多个字符，_ 表示一个字符 "message": {"like": "%windows%"}
'like_binary' string SQL中binary like语法（区分大小写） * 表示0到多个字符， _ 表示一个字符 "message": {"like_binary": "%Windows%"}
'contain' string 包含在数组中 "language": {"contain": "国语"}
'in' array in "_key": {"in": ["_key1", "_key2"]}
‘notin’ array 不在集合中 "_key": {"notin": ["_key1", "_key2"]}

说明：

（1）当“condition”条件为空时，表示获取所有record。

（2）根据key获取一条record，可使用如下condition条件表达：

"_key": {"=": "385d24b3baef3290-1344915172"}

（3）order_by表示支持的排序方式，它是一个数组，数组元素信息如下：

Key Value 描述
列名 asc/desc 将某列按照“asc/desc”排序。

返回参数 (JSON格式)

参数名称 类型 描述
error_code number 错误码，如果不出错，则返回值没有该字段。
error_msg string 错误提示，如果不出错，则返回值没有该字段。
count number 总条目数。
records json array record 数组。

示例

请求示例:

  1. 简单查询
cat > ./artists_select_request <<DELIM
{
    "table": "artists",
    "condition": {
        "and": [                                                                                                                                              
            { "name": { "=": "刘德华" } }
        ]
    },
    "order_by" : [
        {"add_time" : "desc" },
        {"name"     : "asc" }
    ],
    "start": 0,
    "limit": 10
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null
  1. 组合查询
cat > ./artists_select_request <<DELIM
{
    "table": "artists",
    "condition": {
        "and": [                                                                                                                                              
            { "name": { "=": "刘德华" } },
            { "tags": { "contain": "四大天王" } }
        ]
    },
    "projection": ["name", "intro"]
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null
  1. select 支持对嵌套属性的查询
cat > ./artists_select_request <<DELIM
{
    "table": "artists",
    "condition": {
        "and": [                          
            { "top_song.name": { "=": "爱你一万年" } }
        ]
    },
    "projection": ["name", "intro"]
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null |./json_decode
  1. or 条件支持
cat > ./artists_select_request <<DELIM
{
    "table": "artists",
    "condition": {
        "or": [
            { "name": { "=": "刘德华" } },
            { "top_song.name": { "=": "月亮之上" } }
        ]
    },
    "projection": ["name", "intro"]
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null
  1. and/or 混合条件支持
cat > ./artists_select_request <<DELIM
{
    "table": "artists",
    "condition": {
        "or": [
            { "name": { "=": "刘德华" } },
            { "and": [
                { "top_song.name": { "=": "月亮之上" } },
                { "tags": { "contain": "月亮之上" } }
            ]}
        ]
    },
    "projection": ["name", "intro"]
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=select&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_select_request" 2>/dev/null

响应示例：

{
"table":"artists",
"count": 1,
"start": 0,
"limit": 0,
"records": [
{
"_key": "f44603de003c57d5-1346066442",
"name": "刘德华",
"intro": "香港著名歌手、演员",
},
]
}

record增量更新查询

功能

数据更新增量查询接口。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：diff。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 要更新的目标表名。
cursor string 是 用于标记更新的游标。第一次调用时设置cursor=null，第二次调用时，使用上一次调用该接口的返回结果中的cursor。
projection array 否 指定需要哪些字段，“_key”、“_mtime”、“_ctime”是默认返回的。
返回参数
参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段。
error_msg string 错误提示。如果不出错，则返回值没有该字段。
table string 表名。
entries array record 数组。
reset boolean 客户端是否需要清空本地所有数据。True：表示服务器通知客户端清理所有本地数据，从头获取一份完整的数据列表。
has_more boolean 是否还有更新。
  • True：本次调用diff接口结果无法一次返回，立刻再调用一次diff接口获取剩余结果；
  • False：已返回全部更新，等待一段时间（5分钟）之后再调用该接口查看是否有更新。
cursor string 游标，下次调用diff 接口，需要使用该参数

说明：

（1）其中records是一个record数组，标志从上次调用该接口以来的更新操作：

  • 对于update后的record，会得到一个最新版的record；
  • 对于删除的record，得到的record中_isdelete字段为“1”。

（2）常见“reset=true”的场景如下：

  • 服务器端程序升级等，提示客户端重新拉去文件列表等。

（3）注意：

diff接口有一定延迟（约10s），客户端不可假设新增record之后马上就会在diff 接口中获得更新。

示例

请求示例:

当创建了“刘德华”和“凤凰传奇”两个record后，第一次调用diff接口，使用cursor为null作为参数：

 
$ cat > ./artists_diff1_request <<DELIM
{
    "table":"artists",
    "cursor"    : "null",
    "projection": ["name", "intro"]
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/data?method=diff&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_diff1_request"

返回：

{
    "table":"artists",
    "entries":
    [
        {
            "_key": "f44603de003c57d5-1346066442",
            "name": "刘德华",
            "intro": "香港著名歌手、演员",
            "_ctime":1345786801,
            "_mtime":1345786801,
            "_isdelete":0
        },
        {
            "_key": "1aaef0010c012db7-1346066442",
            "name": "凤凰传奇",
            "intro": "中国大陆具有广泛知名度的男女二人音乐组合",
            "_ctime":1345787059,
            "_isdelete":0,
            "_mtime":1345787666
        }
    ],
    "cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a30447a6f4e68774233616130362f63356f67586d66647879736f72686a70757a575a5342582b4c4b506479325431486f3937526333514a4a6d72626d7830574a35456d46705153454c4873614f6a6368743948743575386b45765477376a634e453848457737522f756d714235464d7a374372574b5777675134423231366a6f3431673d3d",
    "request_id":4060333081
}

此时如果删除了“刘德华”，再调用diff接口，应该使用刚才的cursor作为参数调用diff接口：

$ cat > ./artists_diff2_request <<DELIM
{
    "table":"artists","cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a30442b6f6b4f585a7672687647426342783858576a524666316470356473754f6a364356674365366f53647979663646356649744747336e50694a44767a7258627a77473078572b327a366c4f674a4c757a76596e3843454b36496b59474153566c4447514c506632704c64494a5a764f337269546d6d454c6869676765367a4866513d3d",
    "projection": [ "name", "id" ]
}
DELIM
 
curl  -i -X POST
"http://pcs.baidu.com/rest/2.0/structure/data?method=diff&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=artists_diff2_request"

得到的响应如下：

{
    "table":"artists",
    "entries":
    [
        {
            "id":85617,
            "name":"\u5218\u5fb7\u534e",
            "_ctime":1346066442,
            "_mtime":1346067702,
            "_isdelete":1,
            "_key":"f44603de003c57d51346066442"
         }
    ],
    "has_more":false,
    "reset":false,"cursor":"3861315431477246513534776b33573367765677314d595a6571724c69753574426133356f4f71316239342b5937577037766874316330493447465a346172445776504e45793235552b456f39796f4c6b307a304434436368685971496f4e544d446e326a6341505358767251356b79616244597a52745750436d544a327250703956444f7338593752737a4e32735a4d634233372f34416e454e4f3744474c4b4e6d726d64726f774e6b594a4e6553524a716d65743442553375696b354f585738474d376e4f635973507239636c6e5071585141673d3d",
    "request_id":1242060313
}

查询record（回收站）

功能

与select相同，只不过操作对象是回收站中。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

说明

该接口参数与select完全一样, 只不过操作对象是回收站中的records；返回的records中_isdelete为“1”。详细信息，请参考“查询record—select”。

从回收站中恢复record

功能

从回收站中恢复文件。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否必需 描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：restore。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 要恢复的目标表名。
records json array 是 需要恢复的record _key数组。

说明：

其中records是一个数组，每个数组成员结构如下：

名称 类型 是否必需 描述
_key string 是 需要恢复的record _key字段的值。

返回参数

参数名称 类型 描述
error_code number 错误码。如果不出错，则返回值没有该字段
error_msg string 错误提示。如果不出错，则返回值没有该字段
records json array 返回服务器端已经处理的records(_key,_mtime)列表，顺序与输入顺序一致，如果一个请求包含多个record，遇到第一个出错record即中止，返回的records只包含已经处理成功的key。

示例

请求示例: 

$ cat > ./artists_restore_request <<DELIM
{
"table":"artists",
"records": [
{"_key": "7d4febca4a68e763-1344915172"},
{"_key": "385d24b3baef3290-1344915172"}
]
}
DELIM
 
$ curl  -v -X POST
"http://pcs.baidu.com/rest/2.0/structure/data?method=restore&access_token=2.b06c3e00010fdb879d12345dcd5f8545.2587600.134819999.1175746697-238347" -F "param=<artists_restore_request"
 
正确响应示例：
HTTP/1.1 200 OK
{
"records": [
{
"_key":"7d4febca4a68e763-1344915172",
"_mtime":1344927006
},
{
"_key":"385d24b3baef3290-1344915172",
"_mtime":1344927006
},
 
]
}
出错响应示例：
HTTP/1.1 400 Bad Request
{
"error_code":31430,
"error_msg":"key not exist",
"request_id":0
"records": [
{'_key': "7d4febca4a68e763-1344915172"},
]
}

按条件更新record

功能

对符合一定条件的record 执行更新操作。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否

必需

描述
v string 否 版本号，默认为“1.0”
method string 是 固定值：update
type string 是 固定值：by-condition。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 查询的目标表名。
condition json 是 条件描述, 与select 中的condition一样。
action json 是 需要对命中的record进行的操作。

说明：

action为一个json字典，其格式为：
"action": {                                                                     
    column: {action: value}
}
如:
"action": {                                                                     
    "name": {"=": "LiuDeHua"}
}

其中column 支持嵌套列。

  • 所支持的action如下表所示：
action 类型 描述 示例
'=' number/string 表示将目标列设置为value。 "name": {"=": "LiuDeHua"},
'+=' number 表示将目标列的值增加value，如果该列不存在，默认值为0。 "age": {"+=":1},
'-=' number 表示将目标列的值减少value，如果该列不存在，默认值为0。 "age": {"-=":1},

返回参数 (JSON格式)

参数名称 类型 描述
error_code number 错误码，如果不出错，则返回值没有该字段。
error_msg string 错误提示，如果不出错，则返回值没有该字段。
request_id number 请求唯一标识ID。
affected number 返回受影响的行数。

示例

请求示例: 

cat > ./artists_update_request <<DELIM
{
"table": "artists",
"condition": {
"and": [
{ "name": { "=": "刘德华" } }
]
},
"action": {
"name": {"=": "LiuDeHua"},
"age": { "+=": 1 }
}
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=update&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request"
响应示例：
{
"affected": 1,
"request_id": 4060311005
}

按条件删除record

功能

对符合一定条件的record 执行删除操作。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否

必需

描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：delete。
type string 是 固定值：by-condition。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 查询的目标表名。
condition json 是 条件描述，与select 中的condition一样。

返回参数 (JSON格式)

参数名称 类型 描述
error_code number 错误码，如果不出错，则返回值没有该字段。
error_msg string 错误提示，如果不出错，则返回值没有该字段。
request_id number 请求唯一标识ID。
affected number 返回受影响的行数。

示例

请求示例: 

 cat > ./artists_update_request <<DELIM
{
"table": "artists",
"condition": {
"and": [
{ "name": { "=": "LiuDeHua" } }
]
}
}
DELIM
 
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=delete&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request"
响应示例：
{
"affected": 1,
"request_id": 4060311005
}

按条件恢复record

功能

对回收站中符合一定条件的record 执行restore操作。

HTTP请求方式

POST

URL

https://pcs.baidu.com/rest/2.0/structure/data

请求参数

参数名称 类型 是否

必需

描述
v string 否 版本号，默认为“1.0”。
method string 是 固定值：restore。
type string 是 固定值：by-condition。
access_token string 是 用户的access_token，HTTPS调用时必须使用。
table string 是 查询的目标表名。
condition json 是 条件描述, 与select 中的condition一样。

返回参数 (JSON格式)

参数名称 类型 描述
error_code number 错误码，如果不出错，则返回值没有该字段。
error_msg string 错误提示，如果不出错，则返回值没有该字段。
request_id number 请求唯一标识ID。
affected number 返回受影响的行数。

示例

请求示例: 

cat > ./artists_update_request <<DELIM
{
"table": "artists",
"condition": {
"and": [
{ "name": { "=": "LiuDeHua" } }
]
}
}
DELIM
curl  -v -X POST "http://pcs.baidu.com/rest/2.0/structure/data?method=restore&type=by-condition&access_token=2.85e37d20acd37c3a5ebc9726bd5606eb.31536000.1384932826.1175746697-309847" -F "param=<artists_update_request"
响应示例：
{
"affected": 1,
"request_id": 4060311005
}

Reference in New Issue View Git Blame Copy Permalink