跳到主要内容

开发者必读

使用入门

OpenAPI可以管理使用OpenAPI创建的数据源,在Web端添加的数据源,无法通过OpenAPI管理。

  1. API地址:https://open.bdp.cn/api/
  2. 访问权限:OpenAPI目前对所有企业版用户开放, 使用BDP企业版用户名与密码申请访问Token后,即可进行OpenAPI使用;
  3. 用户凭证:BDP使用Token作为账户的唯一凭证,Token目前不会过期,需要妥善保存;
  4. 账户安全:您的Token及BDP账户的用户名和密码会通过Https加密传输;
  5. 数据格式:OpenAPI数据传输均使用JSON格式,具体内容参见各接口;
  6. 接口频率:当前的架构设计对于频繁的小量数据写入处理效率不高,所以建议还是尽量批量的更新数据, 但是大量的数据传输会提高等待时间,因此建议尽量将数据量控制在5万条左右;

接口限制

OpenAPI创建的工作表在使用时限制了刷新频率(commit),请按照如下说明使用。

1.默认创建:接口创建的工作表的最小刷新频率为一小时,即一次提交后需要间隔一个小时以上后,进行下一次提交;

2.高频更新表:高频表适用于数据源基础表(包括Excel)数据需要高频刷新,可以直接在仪表盘作图的场景,最小刷新频率为1分钟,不能进行任何的合表操作,如希望看到每10分钟的最新数据可将工作表调整为高频表;高频表设置在工作表的模块右侧主操作区的工作表名旁边,默认为“普通工作表”,调整前后该表不能参与合表,数据量须小于10万行。

Dev_开发者必读_1.png

3.测试直通车:为了满足开发者在开发调试接口时,需要频繁刷新数据确认结果的场景,为每个管理员账号设置了40个小时的高速通道用于高频更新数据,支持最小刷新频率为1分钟,开启后所有接口创建工作表均生效;可在开发者中心申请,使用完毕需要结束直通车,不足1小时按一小时计算,企业域内共享直通车时间。

Dev_开发者必读_2.png

接口规范

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)中,请不要重复提交

快速开发流程

快速开发流程.png

开发大体按以下步骤进行:

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