# 结构化数据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

2. 组合查询

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

3. 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

4. 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

5. 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
}