1 请求说明
1.1 请求地址
http://api.vhallyun.com/api/v1/controller/action
- controller/action 为每个接口单独提供
1.2 通信协议
请求支持HTTP和HTTPS两种访问方式
1.3 请求方法
同时支持POST&GET方式,GET方式查询字符串(名称/值对)是在GET请求的URL中发送的,POST方式查询字符串(名称/值对)是在POST请求的HTTP消息主体中发送的。
1.4 请求参数
每个请求都需要包含的公共请求参数
1.5 字符编码
所有接口均使用UTF-8编码
2 公共参数
2.1 公共请求参数(如无特殊说明,接口中均包含公共请求参数)
所有接口均需要放置以下公共参数在请求头中,用于标识用户和接口鉴权。后续的接口说明不再对这些参数进行说明,但每次发起请求均需要携带。
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
app_id | string | 是 | 应用ID |
signed_at | string | 是 | 鉴权时间,时间戳 |
sign | string | 是 | 鉴权签名 |
2.2 公共响应参数(如无特殊说明,接口中的响应参数均为data中的数据)
参数 | 类型 | 是否必选 | 含义 |
---|---|---|---|
code | int | 是 | 请求状态码 (200 成功) |
msg | string | 是 | 失败原因(默认空字符串) |
data | json | 是 | 请求数据 |
2.3 公共错误码
参数 | 类型 | 含义 |
---|---|---|
10001 | int | 应用ID不能为空 |
10002 | int | 鉴权时间不能为空 |
10003 | int | 鉴权签名不能为空 |
20001 | int | 应用查询为空 |
20003 | int | 开发者不存在 |
30004 | int | 接口鉴权失败 |
30003 | int | 当前开发者尚未通过认证 |
3 API鉴权方案
使用业界通用方案。
- 我们为客户的每个应用,分配一个app_id和一个secret_key。
- app_id和一个secret_key获取地址 : http://yun.vhall.com/console/app/index (应用->设置->应用信息)
- 客户的所有API请求中,需携带app_id。用于识别应用。
- 同时,客户对请求中所有参数(包括app_id)进行字典序排序,并拼接成字符串。
- 在此字符串首尾各拼接secret_key。
- 对拼接后的字符串进行md5,得到sign。
- 将得到的sign作为请求参数之一传递。
- VOP服务器收到所有参数后,根据app_id取得对应的secret_key,然后依照同样的算法计算sign。验证与传递的sign是否一致。
例如:
$secret_key = "f145b675f441cc00dd3e55746a0f4780";
$params = [
"room_id"=> "123456789",
"app_id"=> "3eb7261",
"signed_at"=> "1484620708"
];
// 按参数名升序排列
ksort($params);
// 将键值组合
array_walk($params,function(&$value,$key){
$value = $key . $value;
});
// 拼接,在首尾各加上$secret_key,计算MD5值
$sign = md5($secret_key . implode('',$params) . $secret_key);