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);