开发者必读

来自BDP个人版帮助中心
跳转至: 导航搜索

使用入门

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提交;

  • 请求参数:
"access_token": "YOUR_TOKEN"	
  • 请求数据:
{ 
	"data1": [						
	    "ID1",
	    "ID2"
	], 
	"data2": "YOUR_DATA2",			//其他参数
	"data3": "YOUR_DATA3",			//其他参数
}

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:

# Install the Python Requests library:
# `pip install requests`

import requests
import json

def send_request():
    # ds/create
    # POST https://open.bdp.cn/api/ds/create

    try:
        response = requests.post(
            url="https://open.bdp.cn/api/ds/create",
            params={
                "access_token": "token",
                "name": "ds_name",
                "type": "opends",
            },
            data=json.dumps({

            })
        )
        print('Response HTTP Status pre: {status_pre}'.format(
            status_pre=response.status_pre))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

java:

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // ds/create (POST )
    
    try {
      
      // Create request
      Content content = Request.Post("https://open.bdp.cn:/api/ds/create?access_token=token&name=ds_name&type=opends")
      
      // Add body
      .bodyString("{}", ContentType.APPLICATION_JSON)
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

php:

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://open.bdp.cn:/api/ds/create?access_token=token&name=ds_name&type=opends');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Create body
$json_array = [

        ]; 
$body = json_enpre($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - pre: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status pre : " . curl_getinfo($ch, CURLINFO_HTTP_pre);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

3. 根据数据源id创建工作表

  • url: tb/create
  • 参数: 上一步返回的ds_id, 表名, 表结构等信息
  • 创建成功后返回tb_id
  • 示例代码:

python:

# Install the Python Requests library:
# `pip install requests`

import requests
import json

def send_request():
    # tb/create
    # POST https://open.bdp.cn/api/tb/create

    try:
        response = requests.post(
            url="https://open.bdp.cn/api/tb/create",
            params={
                "access_token": "token",
            },
            data=json.dumps({
                "title": "工作表",
                "schema": [
                    {
                        "name": "name1",
                        "type": "string",
                        "title": "title1"
                    },
                    {
                        "name": "name2",
                        "type": "string",
                        "title": "title2"
                    }
                ],
                "name": "table",
                "ds_id": "ds_id"
            })
        )
        print('Response HTTP Status pre: {status_pre}'.format(
            status_pre=response.status_pre))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

java:

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // tb/create (POST )
    
    try {
      
      // Create request
      Content content = Request.Post("https://open.bdp.cn:/api/tb/create?access_token=token")
      
      // Add body
      .bodyString("{\"title\": \"工作表\",\"schema\": [{\"name\": \"name1\",\"type\": \"string\",\"title\": \"title1\"},{\"name\": \"name2\",\"type\": \"string\",\"title\": \"title2\"}],\"name\": \"table\",\"ds_id\": \"ds_id\"}", ContentType.APPLICATION_JSON)
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

php:

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://open.bdp.cn:/api/tb/create?access_token=token');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Create body
$json_array = [
            "title" => "工作表",
            "schema" => [
                [
                    "name" => "name1",
                    "type" => "string",
                    "title" => "title1"
                ],
                [
                    "name" => "name2",
                    "type" => "string",
                    "title" => "title2"
                ]
            ],
            "name" => "table",
            "ds_id" => "ds_id"
        ]; 
$body = json_enpre($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - pre: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status pre : " . curl_getinfo($ch, CURLINFO_HTTP_pre);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);


4. 向工作表中写入数据

  • url: data/insert
  • 参数: 上一步返回的tb_id, 数据中的字段(有序的json列表)
  • 数据: 二维json列表, 需转化为字符串的形式
  • 示例代码:

python:

# Install the Python Requests library:
# `pip install requests`

import requests
import json

def send_request():
    # data/insert
    # POST https://open.bdp.cn/api/data/insert

    try:
        response = requests.post(
            url="https://open.bdp.cn/api/data/insert",
            params={
                "access_token": "token",
                "tb_id": "tb_id",
                "fields": "[\"name1\", \"name2\"]",
            },
            data=json.dumps([
                [
                    "test1",
                    "test2"
                ],
                [
                    "test3",
                    None
                ]
            ])
        )
        print('Response HTTP Status pre: {status_pre}'.format(
            status_pre=response.status_pre))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

java:

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // data/insert (POST )
    
    try {
      
      // Create request
      Content content = Request.Post("https://open.bdp.cn:/api/data/insert?access_token=token&tb_id=tb_id&fields=%5B%22name1%22%2C%20%22name2%22%5D")
      
      // Add body
      .bodyString("[[\"test1\",\"test2\"],[\"test3\",null]]", ContentType.APPLICATION_JSON)
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

php:

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://open.bdp.cn:/api/data/insert?access_token=token&tb_id=tb_id&fields=%5B%22name1%22%2C%20%22name2%22%5D');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Create body
$json_array = [
            [
                "test1",
                "test2"
            ],
            [
                "test3",
                null
            ]
        ]; 
$body = json_enpre($json_array);

// Set body
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - pre: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status pre : " . curl_getinfo($ch, CURLINFO_HTTP_pre);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

5. 提交数据

  • url: tb/commit
  • 参数: tb_id
  • 示例代码:

python:

# Install the Python Requests library:
# `pip install requests`

import requests

def send_request():
    # tb/commit
    # GET https://open.bdp.cn/api/tb/commit

    try:
        response = requests.get(
            url="https://open.bdp.cn/api/tb/commit",
            params={
                "access_token": "token",
                "tb_id": "tb_id",
            },
        )
        print('Response HTTP Status pre: {status_pre}'.format(
            status_pre=response.status_pre))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

java:

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // tb/commit (GET )
    
    try {
      
      // Create request
      Content content = Request.Get("https://open.bdp.cn:/api/tb/commit?access_token=token&tb_id=tb_id")
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

php:

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://open.bdp.cn:/api/tb/commit?access_token=token&tb_id=tb_id');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - pre: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status pre : " . curl_getinfo($ch, CURLINFO_HTTP_pre);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);

6. 触发视图更新(批量更新接口)

  • url: tb/update
  • 参数: tb_id列表
  • 示例代码:

python:

# Install the Python Requests library:
# `pip install requests`

import requests

def send_request():
    # tb/update
    # GET https://open.bdp.cn/api/tb/update

    try:
        response = requests.get(
            url="https://open.bdp.cn/api/tb/update",
            params={
                "access_token": "token",
                "tb_ids": "[\"tb_id\"]",
            },
        )
        print('Response HTTP Status pre: {status_pre}'.format(
            status_pre=response.status_pre))
        print('Response HTTP Response Body: {content}'.format(
            content=response.content))
    except requests.exceptions.RequestException:
        print('HTTP Request failed')

java:

import java.io.IOException;
import org.apache.http.client.fluent.*;

public class SendRequest
{
  public static void main(String[] args) {
    sendRequest();
  }
  
  private static void sendRequest() {
    
    // tb/update (GET )
    
    try {
      
      // Create request
      Content content = Request.Get("https://open.bdp.cn:/api/tb/update?access_token=token&tb_ids=%5B%22tb_id%22%5D")
      
      // Fetch request and return content
      .execute().returnContent();
      
      // Print content
      System.out.println(content);
    }
    catch (IOException e) { System.out.println(e); }
  }
}

php:

<?php

// Get cURL resource
$ch = curl_init();

// Set url
curl_setopt($ch, CURLOPT_URL, 'https://open.bdp.cn:/api/tb/update?access_token=token&tb_ids=%5B%22tb_id%22%5D');

// Set method
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');

// Set options
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

// Send the request & save response to $resp
$resp = curl_exec($ch);

if(!$resp) {
  die('Error: "' . curl_error($ch) . '" - pre: ' . curl_errno($ch));
} else {
  echo "Response HTTP Status pre : " . curl_getinfo($ch, CURLINFO_HTTP_pre);
  echo "\nResponse HTTP Body : " . $resp;
}

// Close request to clear up some resources
curl_close($ch);