Skip to content

Commit

Permalink
更新 API 文档
Browse files Browse the repository at this point in the history
  • Loading branch information
jasonelchen committed Oct 16, 2017
1 parent 8748b11 commit c9a4fbd
Showing 1 changed file with 256 additions and 83 deletions.
339 changes: 256 additions & 83 deletions API.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,78 +14,40 @@

### API

#### Conf::setServerHost(string $serverHost)

该静态方法用于设置使用本 SDK 的业务服务器的主机名，如 `www.qcloud.la`，该主机需要外网可访问。

##### 参数

- `$serverHost` - 业务服务器的主机名

##### 返回值

`void`

#### Conf::setAuthServerUrl(string $authServerUrl)

该静态方法用于指定鉴权服务器服务地址，如 `http://mina.auth.com`。

##### 参数

- `$authServerUrl` - 鉴权服务器服务地址

##### 返回值

`void`

#### Conf::setTunnelServerUrl(string $tunnelServerUrl)

该静态方法用于指定信道服务器服务地址，如 `https://ws.qcloud.com`。

##### 参数

- `$tunnelServerUrl` - 信道服务器服务地址

##### 返回值

`void`

#### Conf::setTunnelSignatureKey(string $tunnelSignatureKey)

该静态方法用于指定和信道服务器通信的签名密钥，如 `9f338d1f0ecc37d25ac7b161c1d7bf72` ，该密钥需要保密。

##### 参数

- `$tunnelSignatureKey` - 通信签名密钥

##### 返回值

`void`

#### Conf::setNetworkTimeout(int $networkTimeout)

该静态方法用于设置网络请求超时时长（单位：毫秒），默认值为 30,000 毫秒，即 30 秒。

##### 参数

- `$networkTimeout` - 网络请求超时时长

##### 返回值

`void`

#### Conf::setup(array $config)

可以使用本方法批量设置以上所有配置。
可以使用本方法批量设置所有配置。

##### 参数

- `$config` 支持的配置选项如下：
- `ServerHost` - 业务服务器的主机名
- `AuthServerUrl` - 鉴权服务器服务地址
- `TunnelServerUrl` - 信道服务器服务地址
- `TunnelSignatureKey` - 通信签名密钥
- `NetworkTimeout` - 网络请求超时时长（单位：毫秒）
- `appId` - 可选。微信小程序的 App id
- `appSecret` - 可选。微信小程序的 App secret
- `useQcloudLogin` - 必填。是否使用腾讯云代理登录小程序。会话登录需要使用小程序的 App id 和 App secret 来解密用户信息，腾讯云提供使用腾讯云 App id 和 App secret 代理请求微信进行解密。如果该项为 `false`，则需填写微信小程序 App id 和 App secret。默认为 `true`
- `mysql` - 必填。MySQL 配置。不填则使用小程序解决方案分配机器中默认的 MySQL，若使用自行部署的 MySQL 数据库，则需提供一个类型为 `object` 的配置，具体配置项如下：
- `host` - 必填。MySQL 主机名
- `user` - 必填。MySQL 用户名
- `db` - 必填。MySQL 数据库名
- `pass` - 必填。MySQL 密码，若使用了腾讯云微信小程序解决方案，开发环境下，MySQL 的初始密码为您的微信小程序 appid
- `port` - 选填。MySQL 端口（默认：3306）
- `char` - 选填。MySQL 编码
- `cos` - 必填。腾讯云对象存储配置信息，用于上传模块使用。
- `region` - 必填。COS 的地域
- `fileBucket` - 必填。COS 的 bucket 名
- `uploadFolder` - 必填。COS 上传文件夹名
- `maxSize` - 选填。COS 上传最大大小，默认 5M (单位：M)
- `field` - 选填。COS 上传是 field 名称，默认为 `file`
- `serverHost` - 必填。当前服务器的 hostname
- `tunnelServerUrl` - 必填。信道服务器地址
- `tunnelSignatureKey` - 必填。信道服务签名密钥
- `qcloudAppId` - 必填。腾讯云 AppId
- `qcloudSecretId` - 必填。腾讯云 SecretId
- `qcloudSecretKey` - 必填。腾讯云 SecretKey
- `wxMessageToken` - 必填。微信客服消息通知 token
- `wxLoginExpires` - 可选。微信登录态有效期，默认 7200 秒（单位：秒）

**如果购买了腾讯云小程序解决方案，配置项中 `serverHost`, `tunnelServerUrl`, `tunnelSignatureKey`, `qcloudAppId`, `qcloudSecretId`, `qcloudSecretKey`, `wxMessageToken` 由腾讯云自动下发到您的服务器上。**

自动下发的 SDK 配置文件地址： `/data/release/sdk.config.json`

##### 返回值

Expand Down Expand Up @@ -113,11 +75,12 @@

```php
array(
'code' => 0,
'message' => 'ok',
'data' => array(
'loginState' => 1,
'userinfo' => array(
// 第三方 key
'skey' => 'fy89ayri3h2ifs'
// 微信用户信息
'userInfo' => array(...),
'userinfo' => array(...),
),
)
```
Expand All @@ -126,9 +89,8 @@ array(

```php
array(
'code' => -1,
'message' => '失败原因',
'data' => array(),
'loginState' => 0,
'error' => '失败原因'
)
```

Expand All @@ -146,11 +108,9 @@ array(

```php
array(
'code' => 0,
'message' => 'ok',
'data' => array(
'loginState' => 1,
'userinfo' => array(
// 微信用户信息
'userInfo' => array(...),
),
)
```
Expand All @@ -159,9 +119,8 @@ array(

```php
array(
'code' => -1,
'message' => '失败原因',
'data' => array(),
'loginState' => 0,
'error' => '失败原因'
)
```

Expand All @@ -179,15 +138,23 @@ array(

```php
interface ITunnelHandler {
/*----------------------------------------------------------------
* 初始化时传入用户信息
*----------------------------------------------------------------
* @param array $userinfo 用户信息
*----------------------------------------------------------------
*/
public function __construct ($userinfo);

/*----------------------------------------------------------------
* 在客户端请求 WebSocket 信道连接之后会调用该方法
* 此时可以把信道 ID 和用户信息关联起来
*----------------------------------------------------------------
* @param string $tunnelId 信道 ID
* @param array $userInfo 微信用户信息
* @param string $tunnelUrl 信道地址
*----------------------------------------------------------------
*/
public function onRequest($tunnelId, $userInfo);
public function onRequest($tunnelId, $tunnelUrl);

/*----------------------------------------------------------------
* 在客户端成功连接 WebSocket 信道服务之后会调用该方法
Expand Down Expand Up @@ -327,3 +294,209 @@ array(
'message' => '失败原因',
)
```

## MySQL

### 命名空间

`QCloud_WeApp_SDK\Mysql`

### API

#### MySQL::getInstance()

获取 SDK 连接数据库实例，这个是个 [PDO 连接实例](http://php.net/manual/zh/class.pdo.php)。

##### 参数

无

##### 返回值

返回 PDO Instance

#### Mysql::insert($tableName, $data)

向数据库中插入数据

##### 参数

- `$tableName` - 要操作的数据表名（必填）
- `$data` - 要插入的数据（key-value 的 array 类型）

##### 返回值

受影响的行数（数值类型）。

##### 示例

```php
use QCloud_WeApp_SDK\Mysql\Mysql as DB;

DB::insert('tableName', [
'nickname' => 'Jason',
'age' => 21
]);
```

#### Mysql::select($tableName[, $columns = ['*'], $conditions = '', $operator = 'and', $suffix = ''])

从数据库中查询多条数据

##### 参数

- `$tableName` - 要操作的数据表名（必填）
- `$columns` - 查询出来的列名
- `$conditions` - 查询条件，支持 string、array 和 key-value array 类型
- `$operator` - 条件之间的操作符
- `$suffix` - SQL 语句的后缀，可以用来插入 order、limit 等

##### 返回值

返回一个包含结果集中所有行的数组。

##### 示例

```php
use QCloud_WeApp_SDK\Mysql\Mysql as DB;

// 条件为字符串
$rows = DB::select('tableName', 'nickname = Jason');

// 条件为数组
$rows = DB::select('tableName', ['nickname = Jason']);

// 条件为 key-value 数组
$rows = DB::select('tableName', ['nickname' => 'Jason']);

// 查询结果
// $rows > [['nickname' => 'Jason','age' => 21]]
```

#### Mysql::row($tableName[, $columns = ['*'], $conditions = '', $operator = 'and', $suffix = ''])

从数据库中查询单条数据

##### 参数

- `$tableName` - 要操作的数据表名（必填）
- `$columns` - 查询出来的列名
- `$conditions` - 查询条件，支持 string、array 和 key-value array 类型
- `$operator` - 条件之间的操作符
- `$suffix` - SQL 语句的后缀，可以用来插入 order、limit 等

##### 返回值

返回一个包含结果集中所有行的第一行。

##### 示例

```php
use QCloud_WeApp_SDK\Mysql\Mysql as DB;

// 条件为字符串
$rows = DB::row('tableName', 'nickname = Jason');

// 条件为数组
$rows = DB::row('tableName', ['nickname = Jason']);

// 条件为 key-value 数组
$rows = DB::row('tableName', ['nickname' => 'Jason']);

// 查询结果
// $rows > ['nickname' => 'Jason','age' => 21]
```

#### Mysql::update($tableName, $updates[, $conditions = '', $operator = 'and', $suffix = ''])

从数据库中查询单条数据

##### 参数

- `$tableName` - 要操作的数据表名（必填）
- `$updates` - 更新的数据对象
- `$conditions` - 查询条件，支持 string、array 和 key-value array 类型
- `$operator` - 条件之间的操作符
- `$suffix` - SQL 语句的后缀，可以用来插入 order、limit 等

##### 返回值

受影响的行数（数值类型）。

##### 示例

```php
use QCloud_WeApp_SDK\Mysql\Mysql as DB;

// 条件为字符串
$rows = DB::update('tableName', ['age' => 22], 'nickname = Jason');

// 条件为数组
$rows = DB::update('tableName', ['age' => 22], ['nickname = Jason']);

// 条件为 key-value 数组
$rows = DB::update('tableName', ['age' => 22], ['nickname' => 'Jason']);

// 查询结果
// $rows > 1
```

#### Mysql::delete($tableName, $conditions[, $operator = 'and', $suffix = ''])

从数据库中删除数据

##### 参数

- `$tableName` - 要操作的数据表名（必填）
- `$conditions` - 查询条件，支持 string、array 和 key-value array 类型
- `$operator` - 条件之间的操作符
- `$suffix` - SQL 语句的后缀，可以用来插入 order、limit 等

##### 返回值

受影响的行数（数值类型）。

##### 示例

```php
use QCloud_WeApp_SDK\Mysql\Mysql as DB;

// 条件为字符串
$rows = DB::delete('tableName', 'nickname = Jason');

// 条件为数组
$rows = DB::delete('tableName', ['nickname = Jason']);

// 条件为 key-value 数组
$rows = DB::delete('tableName', ['nickname' => 'Jason']);

// 查询结果
// $rows > 1
```

## COS 对象储存 SDK

### 命名空间

`QCloud_WeApp_SDK\Cos`

### API

#### CosAPI::getInstance()

获取 COS 初始化实例

##### 参数

无

##### 示例

```php
use \QCloud_WeApp_SDK\Cos\CosAPI as Cos;

$cosClient = Cos::getInstance();
$cosClient->upload('mybucket', 'test.txt', 'Hello World')->toArray();
```

更多关于 `Cos::getInstance()` 返回 COS 实例的 API，可以查看 [COS PHP SDK V5 文档](https://github.com/tencentyun/cos-php-sdk-v5)。

0 comments on commit c9a4fbd

Please sign in to comment.