开发者必读
来自海致BDP帮助中心、帮助文档
使用入门
OpenAPI可以管理使用OpenAPI创建的数据源，在Web端添加的数据源，无法通过OpenAPI管理。
- API地址：https://open.bdp.cn/api/
- 访问权限：OpenAPI目前对所有企业版用户开放， 使用BDP企业版用户名与密码申请访问Token后，即可进行OpenAPI使用；
- 用户凭证：BDP使用Token作为账户的唯一凭证，Token目前不会过期，需要妥善保存；
- 账户安全：您的Token及BDP账户的用户名和密码会通过Https加密传输；
- 数据格式：OpenAPI数据传输均使用JSON格式，具体内容参见各接口；
- 接口频率：当前的架构设计对于频繁的小量数据写入处理效率不高,所以建议还是尽量批量的更新数据, 但是大量的数据传输会提高等待时间,因此建议尽量将数据量控制在5万条左右；
接口限制
OpenAPI创建的工作表在使用时限制了刷新频率（commit），请按照如下说明使用。
1. 默认创建：接口创建的工作表的最小刷新频率为一小时，即一次提交后需要间隔一个小时以上后，进行下一次提交；
2. 高频更新表：高频表适用于数据源基础表（包括Excel）数据需要高频刷新，可以直接在仪表盘作图的场景，最小刷新频率为1分钟，不能进行任何的合表操作，如希望看到每10分钟的最新数据可将工作表调整为高频表；高频表设置在工作表的模块右侧主操作区的工作表名旁边，默认为“普通工作表”，调整前后该表不能参与合表，数据量须小于10万行。
3. 测试直通车：为了满足开发者在开发调试接口时，需要频繁刷新数据确认结果的场景，为每个管理员账号设置了40个小时的高速通道用于高频更新数据，支持最小刷新频率为1分钟，开启后所有接口创建工作表均生效；可在开发者中心申请，使用完毕需要结束直通车，不足1小时按一小时计算，企业域内共享直通车时间。
接口规范
OpenAPI是遵循RESTful＋JSON风格的API，使用https协议。
1. 请求方式：POST，所有接口均推荐使用POST方式提交；
2. 请求url：API地址＋接口地址；接口地址命名是由接口类型与接口名组成，如下URL代表"数据源创建"的请求URL；
https://open.bdp.cn/api/ds/create
3. 接口类型有如下四种：
- /api/ds——数据源操作接口，包含数据源的创建、删除、查看；
- /api/tb——工作表操作接口，工作表的增删改查、其中数据的触发更新与清空；
- /api/field——工作表中字段的操作接口，字段的增删改查；
- /api/data——工作表中数据操作接口，数据的添加、更新、删除；
4. 请求数据:
所有参数必须按url编码；参数及数据须符合JSON格式，推荐通过POST提交；
- 请求参数：
传参方式分为“QueryString”和“Body”两种；传参方式为“QueryString”参数都应拼接到url中并使用urlencode编码（特别注意：传参方式为QueryString，且参数类型为Array类型的参数都需要先转换为json字符串再拼接到url中）；传值方式为“Body”的都应放到http body中，并序列化为json字符串，不使用urlencode编码，具体内容详见各接口；
QueryString：
param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 }
Body：
{ "ds_id": "your_ds_id", # 数据源id "name": "tb_name", # 工作表名 "schema": [ # 描述工作表结构(字段列表) { "name": "id", # 字段名 "type": "number", # 字段类型 "remark": "字段备注1", # 字段备注 "title": "字段别名1" # 字段别名 }, { "name": "name", # 字段名 "type": "string", # 字段类型 "remark": "字段备注2", # 字段备注 }, { "name": "birth", # 字段名 "type": "date", # 字段类型 "remark": "字段备注3", # 字段备注 } ], "uniq_key": ["id", "name"], # 主键列表,列表中的字段将作为bdp去重标志 "title": "alias_of_tb", # 工作表别名, "comment": "工作表备注", # 工作表备注 "dereplication": 1 # 是否自动去重标识, 1 去重， 0 不去重 }
请求示例：
curl --request POST --url 'https://open.bdp.cn/api/tb/create?access_token=19de5e0297bfd55097733dfbc87ad79e' --data '{"comment": "tb_comment", "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"}]}'
5. 返回信息：接口返回均有如下三部分，根据不同接口有不同返回结果；
{
"status": 0, //状态码
"errstr": "", //文本日期字段，请求成功时错误信息为空
"result": "" //返回数据
}
数据类型
BDP中数据支持三种数据类型，上传其他数据类型将会报错：
- number：整数支持Int类型，超出范围可以上传，但在BDP无法正常展示；小数无限制；
- string：文本字符串；
- date：日期数据，格式需为“%Y-%m-%d %H:%M:%S”，如“2015-01-01 00:00:00”；不规范的格式会造成计算结果不准确；
返回码
- 以下是全局返回码，详细返回码请查看各接口说明；
- 当出现“内部错误”，是系统错误，请联系客服人员。
| 状态码 | 说明 |
| 0 | 请求成功 |
| 4 | 无效Token |
| 5 | 参数缺失或参数类型不符 |
| 10 | 网络异常，请稍候再试 |
| 10 | 内部错误（接口） |
| 410 | 该工作表不存在 |
| 410 | 无工作表操作权限 |
| 411 | 提交（commit）超过频次限制，请参考接口限制 |
| 412 | 工作表在提交（commit）中，请不要重复提交 |
快速开发流程
开发大体按以下步骤进行:
1. 获取token
- token在数据源界面的开发者中心获取
2. 创建数据源
- url: ds/create
- 参数: 数据源名称
- 创建成功后返回ds_id
- 示例代码:
python:
import json import bdp_helper # 创建数据源 def ds_create(): url = "https://open.bdp.cn/api/ds/create" param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 "name": "opends_ds_name", # 数据源名称 必填 "db_type": "opends" # 数据源类型，默认opends } result = bdp_helper.bdp_request(url, param=param) json_result = json.dumps(result, indent=4) print json_result
3. 根据数据源id创建工作表
- url: tb/create
- 参数: 上一步返回的ds_id, 表名, 表结构等信息
- 创建成功后返回tb_id
- 示例代码:
python:
import json import bdp_helper # 创建工作表 def tb_create(): url = "https://open.bdp.cn/api/tb/create" param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 } payload = { "ds_id": "your_ds_id", # 数据源id "name": "tb_name", # 工作表名 "schema": [ # 描述工作表结构(字段列表) { "name": "id", # 字段名 "type": "number", # 字段类型 "remark": "字段备注1", # 字段备注 "title": "字段别名1" # 字段别名 }, { "name": "name", # 字段名 "type": "string", # 字段类型 "remark": "字段备注2", # 字段备注 }, { "name": "birth", # 字段名 "type": "date", # 字段类型 "remark": "字段备注3", # 字段备注 } ], "uniq_key": ["id", "name"], # 主键列表,列表中的字段将作为bdp去重标志 "title": "alias_of_tb", # 工作表别名, "comment": "工作表备注", # 工作表备注 "dereplication": 1 # 是否自动去重标识, 1 去重， 0 不去重 } result = bdp_helper.bdp_request(url, param=param, payload=payload) json_result = json.dumps(result, indent=4) print json_result
4. 向工作表中写入数据
- url: data/insert
- 参数: 上一步返回的tb_id, 数据中的字段(有序的json列表)
- 数据: 二维json列表, 需转化为字符串的形式
- 示例代码:
python:
import json import bdp_helper # 调用data/insert只是将数据写入bdp缓存，要想在bdp看到结果，需要对相应的表调用tb_commit接口 def data_insert(): url = "https://open.bdp.cn/api/data/insert" param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 "tb_id": tb_id, # tb_id 必填 "fields": json.dumps([ # 字段名列表，没有传入的字段将被置空, 注意:这里需要传json字符串 "id", "name", "birth" ]) } payload = [ # 数据列表 [ # 第一行数据 21, "marry", "2016-12-20 11:23:45" ], [ # 第二行数据 23, "smith", "2016-12-19 11:25:32" ], ] result = bdp_helper.bdp_request(url, param=param, payload=payload) json_result = json.dumps(result, indent=4) print json_result
5. 提交数据
- url: tb/commit
- 参数: tb_id
- 示例代码:
python:
import json import bdp_helper # 提交工作表数据 def tb_commit(): url = "https://open.bdp.cn/api/tb/commit" param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 "tb_id": tb_id # tb_id 必填 } result = bdp_helper.bdp_request(url, param=param) json_result = json.dumps(result, indent=4) print json_result
6. 触发视图更新(批量更新接口)
- url: tb/update
- 参数: tb_id列表
- 示例代码:
python:
import json import bdp_helper # 级联更新工作表数据 def tb_update(): url = "https://open.bdp.cn/api/tb/update" param = { "access_token": "19de5e0297bfd55097733dfbc87ad79e", # token 必填 "tb_ids": json.dumps([tb_id]) # tb_id 必填 } result = bdp_helper.bdp_request(url, param=param) json_result = json.dumps(result, indent=4) print json_result
