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)根据名字获取数据源，返回数据源对象参数:
参数 类型 $name string 返回值
ds(DS object)使用:
$ds = $client->get_ds("ds_name");
delete_ds($name)根据名字删除数据源参数:
参数 类型 $name string 使用:
$client->delete_ds("ds_name");
create_ds($name)根据名字创建数据源，返回创建的数据源对象参数:
参数 类型 $name string 返回值:
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],...)使用:
$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)参数:
参数 类型 可缺省 $name string 否 $schema array 否 $uniq_key array 是 $title string 是 注意：schema中name 和 type是必须的，remark 和title 可选。
使用:
$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)根据名字删除工作表参数:
参数 类型 $name string 使用:
$ds->delete_table("table_name");
get_table($name)根据名字获取工作表参数:
参数 类型 $name string 使用:
$tb = $ds->get_table("table_name");
update($tb_ids)根据工作表id列表更新相应工作表参数:
参数 类型 $tb_ids array 使用:
$ds->update(array($tb->get_id()));
update_all()级联更新该数据源的下的所有工作表使用:
$ds->update_all();
get_id()获取数据源ID使用:
$ds->get_id()
get_name()获取数据源名称使用:
$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)向指定的字段插入数据，根据字段名称参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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条件批量删除数据参数:
参数 类型 可缺省 $where string 否 使用:
$tb = $ds->get_table("table_name"); $where = "`id` > 3"; $tb->bulk_delete($where);
delete_data_by_name($fields, $data)根据fields列表中的字段名删除数据行参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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删除数据行参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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列表中的字段名更新数据行参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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更新数据行参数:
参数 类型 可缺省 $fields array 否 $data array 否 使用:
$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()提交原始工作表使用:
$tb->commit()
revert()回滚原始工作表中未提交的数据使用:
$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();