工作表操作

工作表的唯一标识是工作表ID，可通过数据源查看或工作表查看获取；

特别注意

• 对工作表内数据的所有操作（增、删、改）都只是记录在缓存文件中，不影响线上BDP中已有数据，也就是在Web端与移动端都不可见；
• 使操作生效须先后执行提交（commit）和更新（update），注意顺序；
• 提交（commit）是将缓存文件中的操作执行到线上BDP中，使数据生效，可以在Web端与移动端中看到结果；
• 更新（update）是将操作更新到其他相关表中，即使用被操作表生成的其他工作表中；
• 提交（commit）和更新（update）消耗时间与数据量成正比，当数据量较大时请耐心等待；
• 推荐集中对工作表操作后统一进行提交（commit）和更新（update），可以节约大量等待时间；
• 提交（commit）和更新（update）操作对于同一张工作表均不支持并发，如不能并发向一张工作表提交数据，请顺序执行；
• 原数据写入接口tb_insert即将下线，请使用新的数据操作接口进行数据的写入以及更新，使用方式参见数据操作接口；

创建工作表

创建BDP工作表，工作表将出现在工作表视图中以所属数据源命名的文件夹内。

• 同一个数据源下工作表不能重名；
• 工作表内字段名不能重复；
• 字段名称不可修改，可通过添加别名修改在Web端与移动端中看到名称，别名也不能重名；
• 字段名称与字段类型比必选设置，字段备注为可选设置；
• 字段类型只允许为number、string、date之一；
• 可设置主键索引，支持联合主键,功能与MySQL主键类似.主键所在列的数据不能重复。主键值相同时，后面的数据会覆盖前面的数据；

请求URL：

https://open.bdp.cn/api/tb/create

请求方式：POST

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	无限制

Body说明：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
name	string	必填	无	工作表名称，创建后无法修改	1024
ds_id	string	必填	无	数据源唯一标识，创建数据源的时候会生成	无限制
schema	Array	必填	无	Field对象列表	无限制
uniq_key	Array	可选	[]	主键列表,列表中的字段将作为bdp去重标志	无限制
title	string	可选	无	工作表别名	1024
remark	string	可选	无	工作表备注	100
dereplication	int	可选	1	去重标识， 0 不去重 1 去重，uniq_key有值时不能为0	1

schema为Field对象的集合，单个Field数据结构如下：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
name	string	必填	无	字段名称	256
type	string	必填	无	字段类型，只能是string,number,date类型，且区分大小写（例如:不能为STRING等）	未限制
remark	string	可选	无	字段备注	256
title	string	可选	无	字段别名	256

请求示例：

curl --request POST --url 'https://open.bdp.cn/api/tb/create?access_token=19de5e0297bfd55097733dfbc87ad79e' --data '{"remark": "tb_remark", "name": "tb_name", "title": "alias_of_tb", "ds_id": "ds_adf126f84a114d88bb6f6688b97b8053", "dereplication": 1, "uniq_key": ["id"], "schema": [{"remark": "field_remark", "type": "number", "name": "id", "title": "field_title"}]}'

请求成功时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": {
        "tb_id": "TB_ID"                //工作表ID
    }
}

请求错误时返回说明示例：

{
    "status": 4,
    "errstr": "无数据源操作权限"
}

错误代码说明：

status	errstr
4	无数据源操作权限
6	缺少"uniq_key"索引参数，无索引时填空
6	"body"中数据JSON格式不正确
6	字段类型不正确，只允许为number、date、string
101	内部错误（文件夹归属）
102	内部错误（数据源信息）
404	内部错误（创建工作表）
404	内部错误（移动至文件夹）
601	内部错误（创建文件夹）

提交工作表数据

最近写入数据的操作被保存在缓存文件中，调用该接口可以使操作生效。

请求URL：

https://open.bdp.cn/api/tb/commit

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_id	string	必填	无	工作表唯一标识	未限制

请求示例：

curl --request GET --url 'https://open.bdp.cn/api/tb/commit?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512'

请求成功时返回说明：

{
    "status": 0,
    "errstr": "",
    "result": "success"
}

请求错误时返回说明：

{
    "status": 408,
    "errstr": "error message"
}

错误代码说明：

status	errstr
408	工作表正在被使用，请稍候再试
408	内部错误（提交数据）

回滚工作表未提交数据

将工作表数据回滚到上一次commit的版本。

请求URL：

https://open.bdp.cn/api/tb/revert

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_id	string	必填	无	工作表唯一标识	未限制

请求示例：

curl --request GET --url 'https://open.bdp.cn/api/tb/revert?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512'

请求成功时返回说明：

{
    "status": 0,
    "errstr": "",
    "result": "success"
}

请求错误时返回说明：

{
    "status": 408,
    "errstr": "error message"
}

错误代码说明：

status	errstr
408	工作表正在被使用，请稍候再试
413	内部错误（回滚数据）

更新视图

触发级联更新，使对该工作表数据进行的操作，对其他由该工作表生成的其他工作表生效。支持批量操作，可同时更新多张工作表。

请求URL：

https://open.bdp.cn/api/tb/update

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_ids	Array	必填	无	需要进行级联更新的基础表id列表，注意：传参方式为QueryString且参数类型为Array的参数需要先转换为json字符串再拼接到url	未限制

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/update?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_ids=%5B%22tb_cc8bea1e64fb4794976eafd1d6546512%22%5D'

请求成功时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": "success"
}

请求失败时返回说明示例：

{
    "status": 105,
    "errstr": "error message"
}

错误代码说明：

status	errstr
105	返回错误原因详情

预览工作表数据

只能显示已经提交的数据，不能显示缓存的数据。

• 结果为随机抽取的2000条线上数据，不足2000条显示全部；
• 返回表结构中的“uniq_index”为主键索引标记，1为主键，0为非主键；

请求URL：

https://open.bdp.cn/api/tb/preview

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	无限制
tb_id	string	必填	无	工作表唯一标识	未限制

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/preview?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512'

请求成功时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": {
        "schema": [                         //工作表结构
            {
                "name": "id",                 //字段名称
                "uniq_index": 1,              //是否为唯一键值索引
                "type": "number"              //字段类型
            },
                {
                "name": "name",
                "uniq_index": 0,
                "type": "string"
            },
            {
                "name": "birth",
                "uniq_index": 0,
                "type": "date"
            }
        ],
        "data": [                             //工作表数据，与字段结构一一对应
            [
                "4",
                "1993-05-12 13:02:13",
                "Raven"
            ],
            [
                "19",
                "sun",
                "1994-08-13 02:41:50"
            ],
            [
                "7",
                "1991-09-07 12:34:56",
                "John"
            ]
        ],
        "data_count": 3,                      //数据量
        "utime": "2015-11-06 11:04:24"        //工作表的最后更新时间
    }
}

错误代码说明：

status	errstr
405	内部错误（预览数据）

查询数据源下的工作表

查看账户内某个数据源下工作表的详细信息。

请求URL：

https://open.bdp.cn/api/tb/list

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
ds_id	string	必填	无	数据源下唯一标识	未限制

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/list?access_token=19de5e0297bfd55097733dfbc87ad79e&ds_id=ds_adf126f84a114d88bb6f6688b97b8053'

请求成功时返回说明示例：

{
    "status": "0",
    "errstr": "",
    "result": [                               //工作表详情列表
        {                                    //工作表1
            "tb_name": "TB1_NAME",          //工作表名
            "db_id": "DB1_ID",                //数据源ID
            "name": "example_table",        //工作表名
            "data_count": 1000,               //数据量
            "title": "TB1_ALIAS",           //工作表别名，平台中展现的名称
            "db_type": 1,                    //数据源类型
            "tb_id": "TB1_ID",                //工作表ID
            "db_title": "TB1_TITLE",        //数据源别名
            "type": 1,                         //工作表类型
            "id": 43755,                     //id
            "ctime": "2015-11-05 14:56:46"  //创建时间
        },
        {                                    //工作表2
            "tb_name": "TB2_NAME",
            "db_id": "DB1_ID",
            "name": "example_table1",
            "data_count": 2000,
            "title": "TB2_ALIAS",
            "db_type": 1,
            "tb_id": "TB2_ID",
            "db_title": "TB2_TITLE",
            "type": 1,
            "id": 44221,
            "ctime": "2015-11-05 18:37:30"
        }
    ]
}

请求失败时返回说明示例：

{
    "status": "102",
    "errstr": "error message"
}

错误代码说明：

status	errstr
102	内部错误（数据源信息）
407	内部错误（查看工作表）

修改工作表属性

修改工作表别名，不影响工作表ID和名称。

请求URL：

https://open.bdp.cn/api/tb/modify

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_id	string	必填	无	工作表唯一标识	未限制
name	string	可选	无	修改后工作表名称，非原名	1024
dereplication	int	可选	无	是否自动去重标识, 1 去重， 0 不去重， 不传默认为1， 当uniq_key有值时不能为0	1

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/modify?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512&name=alias_of_tb&dereplication=1'

请求成功时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": ""
}

请求失败时返回说明示例：

{
    "status": 6,
    "errstr": "error message"
}

错误代码说明：

status	errstr
6	参数不全
401	工作表ID错误，没有该工作表

清空工作表下数据

清空该表的所有数据，请谨慎使用。

请求URL：

https://open.bdp.cn/api/tb/clean

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_id	string	必填	无	工作表唯一标识	未限制

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/clean?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512'

请求成功时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": "success"
}

请求失败时返回说明示例：

{
    "status": 406,
    "errstr": "error message"
}

错误代码说明：

状态码	说明
406	内部错误（清空数据）

删除工作表

强制删除工作表，会使使用该工作的图表失效，建议在Web端操作。

请求URL：

https://open.bdp.cn/api/tb/delete

请求方式：GET

请求参数说明：

QueryString：

参数名称	参数类型	是否必填	默认值	参数描述	最大长度
access_token	string	必填	无	开发者中心获取token，用来作为用户的身份认证	未限制
tb_id	string	必填	无	工作表唯一标识	未限制

请求示例：

curl --request GET   --url 'https://open.bdp.cn/api/tb/delete?access_token=19de5e0297bfd55097733dfbc87ad79e&tb_id=tb_cc8bea1e64fb4794976eafd1d6546512'

请求失败时返回说明示例：

{
    "status": 0,
    "errstr": "",
    "result": "success"
}

请求成功时返回说明示例：

{
    "status": 403,
    "errstr": "error message"
}

错误代码说明：

status	errstr
403	内部错误（删除工作表）