SDK for PHP
A PHP version development kit for OpenAPI's HTTP-based Core APIs.
下载地址
SDK引入
<?php
require_once('opends.php');
// 请在开发者中心获取所需的access_token
$client = new BDPClient(ACCESS_TOKEN, "domain");
注意事项
- 字符编码使用UTF-8
- 支持的数据类型：number, string, date(建议使用 %Y-%m-%d %H:%M:%S 格式)
- 数据源名, 工作表名, 同一张表的不同字段名, title不可重复
- 当前的架构设计对于频繁的小量数据写入处理效率不高，所以建议还是尽量批量的更新数据， 但是大量的数据传输会提高等待时间，因此建议尽量将数据量控制在5万条左右
- ACCESS_TOKEN从BDP网站的开发者中心获取
SDK简介
| 所属类 | 方法 | 说明 |
|---|---|---|
| BDPClient | get_all_ds | 获取所有数据源 |
| get_ds | 获取数据源 | |
| delete_ds | 删除数据源 | |
| create_ds | 创建数据源 | |
| DS | get_all_tables | 获取该数据源的所有工作表 |
| create_table | 创建工作表 | |
| delete_table | 删除工作表 | |
| get_table | 获取工作表 | |
| update | 更新相应工作表 | |
| update_all | 更新所有工作表 | |
| get_id | 获取数据源id | |
| get_name | 获取数据源名称 | |
| Table | insert_data_by_name | 插入数据 |
| insert_data_by_id | 插入数据 | |
| bulk_delete | 批量删除数据 | |
| delete_data_by_name | 删除数据行 | |
| delete_data_by_id | 删除数据行 | |
| update_data_by_name | 更新数据行 | |
| update_data_by_id | 更新数据行 | |
| commit | 提交原始工作表 | |
| revert | 回滚原始工作表未提交的数据 | |
| clean | 清空该工作表 | |
| get_fields | 列出所有字段 | |
| add_field | 添加指定字段 | |
| delete_field | 删除指定字段 | |
| modify_table | 修改表的别名 | |
| preview | 预览数据 | |
| get_info | 获取表信息 | |
| get_id | 获取表id | |
| get_name | 获取表名称 | |
| modify_field | 修改字段属性 |
SDK说明
BDPClient
用于初始化客户端，进行数据源增、删、查等操作。需要获取access_token作为参数。
构造函数
- `BDPClient($access_token, $domain)`
- 使用:
```
$client = new BDPClient(ACCESS_TOKEN, "domain");
```
实例函数
- `get_all_ds()` 获取所有数据源对象，返回键为名字，值为相应数据源对象的字典。
- 返回值: `array("name1" => [DS object],...)`
- 使用:
```
$all_ds = $client->get_all_ds();
```
- `get_ds($name)` 根据名字获取数据源，返回数据源对象
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
</tr>
</table>
- 返回值 `ds(DS object)`
- 使用:
```
$ds = $client->get_ds("ds_name");
```
- `delete_ds($name)` 根据名字删除数据源
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
</tr>
</table>
- 使用:
```
$client->delete_ds("ds_name");
```
- `create_ds($name)` 根据名字创建数据源，返回创建的数据源对象
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
</tr>
</table>
- 返回值: `ds(DS object)`
- 使用:
```
$client->create_ds("ds_name");
```
DS
数据源类，可以管理该数据源内的各种工作表，并对工作表进行增、删、改、查操作。
通过调用BDPClient类的create_ds方法来创建DS对象,不能通过直接实例化DS类来创建数据源。 通过调用Client类的get_ds方法来获取相应的DS对象。
构造函数
- `DS($name, $token)`
实例函数
- `get_all_tables()` 获取该数据源的所有工作表对象，返回键为表名，值为工作表对象的字典
- 返回值: `array("name1" => [Table object],...)`
- 使用:
```php
$all_tables = $ds->get_all_tables();
```
- `create_table($name, $schema, $uniq_key=NULL, $title=NULL)` 在该数据源中创建工作表，返回该工作表, schema中的type只能是"string"/"number"/"date"其中一种。title参数为表别名（即显示在web端的名字）。
- 返回值: `table (Table Object)`
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
<td>否</td>
</tr>
<tr>
<td>$schema</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$uniq_key</td>
<td>array</td>
<td>是</td>
</tr>
<tr>
<td>$title</td>
<td>string</td>
<td>是</td>
</tr>
</table>
注意：schema中name 和 type是必须的，remark 和title 可选。
- 使用:
```php
$schema = array(
array('name' => 'id', 'type' => 'number', 'remark' => 'id', 'title' => 'field1'),
array('name' => '店号', 'type' => 'number', 'remark' => '', 'title' => 'field2'),
array('name' => '日期', 'type' => 'date', 'remark' => '', 'title' => 'field3'),
array('name' => '时间', 'type' => 'number', 'remark' => '', 'title' => 'field4'),
array('name' => '机台号', 'type' => 'number', 'remark' => '', 'title' => 'field5'),
array('name' => '发票号', 'type' => 'number', 'remark' => '', 'title' => 'field6'),
array('name' => '收银号', 'type' => 'number', 'remark' => '', 'title' => 'field7'),
array('name' => '会员号', 'type' => 'number', 'remark' => '', 'title' => 'field8'),
);
$tb = $ds->create_table("table_name", $schema, array("id"), "title");
```
- `delete_table($name)` 根据名字删除工作表
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
</tr>
</table>
- 使用:
```php
$ds->delete_table("table_name");
```
- `get_table($name)` 根据名字获取工作表
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$name</td>
<td>string</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
```
- `update($tb_ids)` 根据工作表id列表更新相应工作表
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
</tr>
<tr>
<td>$tb_ids</td>
<td>array</td>
</tr>
</table>
- 使用:
```php
$ds->update(array($tb->get_id()));
```
- `update_all()` 级联更新该数据源的下的所有工作表
- 使用:
```php
$ds->update_all();
```
- `get_id()` 获取数据源ID
- 使用:
```php
$ds->get_id()
```
- `get_name()` 获取数据源名称
- 使用:
```php
$ds->get_name()
```
Table
工作表类，对工作表进行增、删、改的操作。
通过调用DS类的create_table方法而不是通过实例化Table类来创建新表。 通过调用DS类的get_table方法来获取相应表的Table实例。
构造函数
- `Table($ds, $name, $tb_id, $schema, $uniq_key=NULL, $title=NULL)`
实例函数
- `insert_data_by_name($fields, $data)` 向指定的字段插入数据，根据字段名称
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"id",
"店号",
"日期",
"台机号",
"发票号",
"收银号",
"供应商号",
"商品描述"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->insert_data_by_name($fields, $data);
```
- `insert_data_by_id($fields, $data)` 向指定的字段插入数据，根据字段id
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"fkddew232",
"fk32d2dw2",
"fk32qe2wq",
"fk29j2e32",
"fk328e2e2",
"fk2eqwq7w",
"fk2d38hae",
"fk73227e2"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->insert_data_by_id($fields, $data);
```
- `bulk_delete($where)` 根据where条件批量删除数据
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$where</td>
<td>string</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$where = "`id` > 3";
$tb->bulk_delete($where);
```
- `delete_data_by_name($fields, $data)` 根据fields列表中的字段名删除数据行
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"id",
"店号",
"日期",
"台机号",
"发票号",
"收银号",
"供应商号",
"商品描述"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->delete_data_by_name($fields, $data);
```
- `delete_data_by_id($fields, $data)` 根据fields列表中的字段id删除数据行
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"fkddew232",
"fk32d2dw2",
"fk32qe2wq",
"fk29j2e32",
"fk328e2e2",
"fk2eqwq7w",
"fk2d38hae",
"fk73227e2"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->delete_data_by_id($fields, $data);
```
- `update_data_by_name($fields, $data)` 根据fields列表中的字段名更新数据行
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"id",
"店号",
"日期",
"台机号",
"发票号",
"收银号",
"供应商号",
"商品描述"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->update_data_by_name($fields, $data);
```
- `update_data_by_id($fields, $data)` 根据fields列表中的字段id更新数据行
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$fields</td>
<td>array</td>
<td>否</td>
</tr>
<tr>
<td>$data</td>
<td>array</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$fields = array(
"fkddew232",
"fk32d2dw2",
"fk32qe2wq",
"fk29j2e32",
"fk328e2e2",
"fk2eqwq7w",
"fk2d38hae",
"fk73227e2"
);
$data = array(
array(0, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(1, 123, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述"),
array(2, 124, "1993-09-07 12:34:56", 11, 3, 343242, 324242, "商品描述")
);
$tb->update_data_by_id($fields, $data);
```
- `commit()` 提交原始工作表
- 使用:
```php
$tb->commit()
```
- `revert()` 回滚原始工作表中未提交的数据
- 使用:
```php
$tb->revert()
```
- `clean()` 清空该工作表的数据
- 使用:
```php
$tb->clean()
```
- `get_fields()` 列出所有字段
- 返回值:
```php
array(
array(
"name" => "xxx",
"uniq_index" => 0/1,
"type" => "number"/"string"/"date",
"remark": ""
),
array(...)
)
```
- `add_field($field_name, $field_type, $uniq_index=0, $title=NULL)` 添加指定字段, field_type只能是"string"/"number"/"date"其中一种,$uniq_index为1指定该字段为主键，为0则指定为非主键,$title为字段别名，可缺省。
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$field_name</td>
<td>string</td>
<td>否</td>
</tr>
<tr>
<td>$field_type</td>
<td>string</td>
<td>否</td>
</tr>
<tr>
<td>$uniq_index</td>
<td>int</td>
<td>是</td>
</tr>
<tr>
<td>$title</td>
<td>string</td>
<td>是</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$tb->add_field("field_name", "string", 0, "alias_field");
```
- `delete_field($field_name)` 删除指定字段
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$field_name</td>
<td>string</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$tb->delete_field("field_name");
```
- `modify_table($alias_name)` 修改表的别名（在web端显示的名称)
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$alias_name</td>
<td>string</td>
<td>否</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$tb->modify_table("alias_name");
```
- `modify_field($field_name, $field_type, $uniq_index=0, $title=NULL)` 修改字段属性, field_type只能是"string"/"number"/"date"其中一种, $uniq_index为1指定该字段为主键，为0则指定为非主键,$title为字段别名，可缺省。
- 参数:
<table>
<tr>
<th>参数</th>
<th>类型</th>
<th>可缺省</th>
</tr>
<tr>
<td>$field_name</td>
<td>string</td>
<td>否</td>
</tr>
<tr>
<td>$field_type</td>
<td>string</td>
<td>否</td>
</tr>
<tr>
<td>$uniq_index</td>
<td>int</td>
<td>是</td>
</tr>
<tr>
<td>$title</td>
<td>string</td>
<td>是</td>
</tr>
</table>
- 使用:
```php
$tb = $ds->get_table("table_name");
$tb->modify_field("field_name", "string", 0, "alias_field");
```
- `preview()` 预览数据
- 返回值:
```php
array(
"schema" => array(
array(
"remark" => "",
"name" => "name",
"type": "string",
"uniq_index": 0
),
array(...)
),
"data" => array(...),
"data_count" => 3,
"utime" => "2015-03-24 18:02:36",
"status" => 0,
"can_partition" => NULL,
"partition" => NULL,
"materialized" => 1,
)
```
- `get_info()` 获取表信息
- 返回值:
```php
array(
"fields" => array(
array(
"type" => "string",
"field_id" => "fk9sadha",
"name" => "saa",
"title" => ""
),
array(...)
),
"tb_id" => "tb_id",
"name" => "name",
"data_count" => 100,
"title" => "date_test"
)
```
- `get_id()` 获取工作表ID
- 使用:
```php
$tb->get_id()
```
- `get_name()` 获取工作表名称
- 使用:
```php
$tb->get_name()
```
异常信息
所有的服务器端异常都将抛出包含错误码以及错误信息的Exception，错误码可以参照API文档
本地的异常将直接抛出带错误信息的Exception
示例
- 获取指定数据源对象并获取其中所有的工作表
<?php
require_once('opends.php');
$client = new BDPClient(ACCESS_TOKEN, "domain");
$all_ds = $client->get_all_ds();