托管产品说明

名词解释

C端用户：业务平台的最终用户，若在萤石平台注册，称为萤石“C用户”，以区别同样在萤石平台注册，但利用萤石开发平台进行业务开发，使用业务平台为最终用户提供服务的“B账号”。通常设备注册到萤石平台，并和“C用户”关联，然后由“C用户“把部分权限授权给”B账号“，称为”托管“。

授权码回调/设备授权回调： 通过开发者提供的回调地址，以回调地址+参数的形式将用户的设备授权信息传给开发者服务器。

最佳实践

开发者配置授权页

开发者配置授权页展示信息

授权登录页：

以上界面由萤石开放平台提供，其中logo、应用名、公司名以及服务介绍等可通过开发者服务账号及应用信息配置同步，如下图：

路径分别为：

萤石开放平台官网$\to$开发者服务$\to$我的应用（同步应用服务介绍、应用名及应用logo）

萤石开放平台官网$\to$开发者服务$\to$账号信息（同步企业名）

开发者配置授权页路径

授权登录页地址: https://openauth.ys7.com/trust/device?client_id={appKey}&response_type=code&state={state}

参数说明:

可以将拼接过参数的url生成二维码或某注册页面、账户配置页面的链接；

state用于最终C端用户授权行为发生时，回调给开发者服务端，所以可以用state区分业务类别、用户身份

例：

物业管理平台，自行提供家庭登记页面，当最终用户填写了家庭信息后，前往state=家庭信息标识的授权页，将设备授权给开发者，这样开发者收到授权设备后，可以将这些设备标记为这个家庭。

用户登录授权+用户提交授权设备信息

用户可通过开发者提供的授权页进入授权登录页： 用户可通过开发者提供的授权页进入授权登录页： 登陆后，可以查看到自己萤石账号下所有的设备，在‘我的设备’标签中，选择想要授权的设备，然后点击提交，开发者会通过被萤石服务器回调而收到授权码和授权信息。 选择授权设备时，可以同步对每台设备配置C用户自定义设备信息，用于开发者后续获取托管设备列表时，参考备注信息对设备进行对应处置

开发者账户获取授权设备信息

开发者通过向萤石云平台提供回调接口后，用户进行授权操作时，平台会通过以下两个接口给到开发者授权信息： 授权码回调： {callBackAddress}?auth_code=value&state= 授权信息（设备）回调： Url:{callBackAddress}?opt_type=opt&deviceSerials=deviceSerials&deviceTrustId=deviceTrustId&state=customInfo

1. 在授权过程中开放平台会先将auth_code以及state给开发者,，auth_code有效时长为10分钟
2. 开发者拿到auth_code,后通过auth_code和开发者的access_token请求到开放平台获取授权信息接口（获取设备授权信息）
3. 收到授权信息后,返回给开放平台服务成功：200,返回其他字符则会接口调用失败.
4. 获取authcode这次操作返回平台成功后，平台认为该次授权成功，最后返回给用户授权成功
5. 授权成功后，平台会再回调一次，将授权设备和用户设备授权id- deviceTrustId传给开发者

接口协议详情见协议文档

开发者利用授权token控制授权设备

关于托管中的Token

托管/授权关系中，开发者会同时存在4种token：

• 开发者token：开发者自身的token，目前暂时无法操作授权设备，仅用于调用授权设备控制类（包含获取授权设备列表）接口外的其他接口
• 授权设备刷新token：与开发者&授权用户关系存在唯一关联，用于刷新授权设备token，刷新token目前会长久存在，刷新token只能通过授权回调中的auth_code获得；
• 授权设备token：主要通过刷新token获取，在获取刷新token时，也会给到，用于授权设备的实际操作，同样与开发者&授权用户关系存在唯一关联，通过该token获取托管设备列表时，可以获取到所有跟该token关联的用户所授权给该开发者的设备，同样，该token所能操作的设备权限仅限于该token对应用户授权的设备
• 授权设备ALL权限token：可以通过开发者appkey及sercret获取，该token和授权设备token用法类似，但是不与某用户、用户关系绑定，可以操作所有开发者下的授权设备和能够获取到所有授权设备。

授权设备的操作方式

PS：授权设备实际上也包含多种scope-权限，目前默认只能生成设备ALL权限的授权页，所以该版本暂时不需要关心

1. 通过获取托管设备列表接口，可以获取到参数中token权限覆盖的授权设备
2. 使用ezopen播放和sdk播放函数播放时，操作的设备需传入有该设备操作权限的token，授权设备ALL权限token或该设备对应的授权设备token
3. 当不操作授权设备时，开放平台的所有需要用到token的接口，均使用开发者token即可
4. 目前支持的能力：预览（不支持直播地址）、回放、告警消息（alarm）订阅、云台控制、子账号、抓图、探测器网关

设备托管协议文档

开发者H5授权登录页地址

开放平台会提供开发者授权的授权登录页地址,开发者可以根据地址生成二维码等,来引导C用户完成授权流程. 授权登录页地址: https://openauth.ys7.com/trust/device?client_id={appKey}&response_type=code&state={state} 参数说明：

授权登录页展示：

以上界面由萤石开放平台提供，其中logo、应用名、公司名以及服务介绍等可通过开发者服务账号及应用信息配置同步，如下图： 路径分别为： 萤石开放平台官网$\to$开发者服务$\to$我的应用（同步应用服务介绍、应用名及应用logo） 萤石开放平台官网$\to$开发者服务$\to$账号信息（同步企业名）

C用户通过授权登录页可选择授权设备及备注设备信息，完成授权后授权信息将调取回调地址返回给开发者

平台集成开发者回调地址逻辑

授权码回调

开发者需要提供回调地址给开放平台后台管理员,地址协议形式为HTTPS/HTTP,同时整个请求地址由开发者自定义.开放平台会通过开发者的回调地址,将授权码以参数形式给到开发者,参数名为auth_code.开发者只需要通过auth_code来获取需要的授权信息.开发者接口设计逻辑可参照下图:

如上图:

1. 在授权过程中开放平台会将auth_code以及state给开发者, auth_code有效时长为10分钟
2. 开发者拿到auth_code,通过auth_code和开发者的access_token请求到开放平台获取授权信息接口
3. 收到授权信息后,返回给开放平台服务成功,返回其他字符则会接口调用失败.

接口协议如下: 请求地址: {callBackAddress}?auth_code=value&state=customInfo 请求方式 Get 返回信息

{
    "code": "200"
}

注：返回上述信息,则开放平台认为开发者信息获取成功.返回其他任何信息,均认为失败.

授权信息（设备）回调

接口协议如下: 请求地址 {callBackAddress}?opt_type=opt&deviceSerials=deviceSerials&deviceTrustId=deviceTrustId Opt = “device_authorize” => 设备授权 Opt= “device_cancel” => 取消授权 deviceSerials : 用户操作的设备序列号 一般为 deviceSerial : channelNo, 多个设备直接 用 逗号(,)分隔 deviceTrustId： 授权用户id, 表示设备来源 state：

请求方式 Get

返回信息

{
    "code": "200"
}

注：返回上述信息,则开放平台认为开发者信息获取成功.返回其他任何信息,均认为失败.

相关接口说明

开发者通过授权码获取授权信息（确认设备授权）

功能描述： 该接口主要是开发者通过授权码获取授权信息,该token主要是用来获取单个用户下对应的托管设备.

请求地址： https://open.ys7.com/api/lapp/trust/device/token/get

请求参数：

请求报文：

POST /trust/device/token/get HTTP/1.1
Host: openauth.ys7.com
Content-Type: application/x-www-form-urlencoded
access_token =at.dunwhxt2azk02hcn7phqygsybbw0wv6p&auth_code=dshfksdhf

返回信息

{
    "data": {
        "access_token": "du.2svbvjn82ycx5weh54slfbuebmn6im7o-3np7vpbklx-0zxzdhk-fkzgcpc84",
        "expires_in": 1541656437269,
        "refresh_token": "rt.99oz60qc8hn1jfwp9ml4nttid9u3w9h0-8s2wqprgxs-0zhci16-sssvtcmdk",
        "openId": "b4a3edff6af84a71b8a12912094359b5",
    },
    "code": "200",
    "msg": "操作成功"
}

返回字段:

返回码:

刷新设备托管token接口

功能说明 该接口主要是用来刷新过期的设备托管token

请求地址 https://openauth.ys7.com/oauth/token/refreshToken

请求参数

请求报文

GET/oauth/token/refreshToken HTTP/1.1
Host: openauth.ys7.com
Content-Type: application/x-www-form-urlencoded
refresh_token =dr.dunwhxt2azk02hcn7phqygsybbw0wv6p& client_id =dshfksdhf&open_id=asjdkasd&grant_type= refresh_token&access_token=at.sadasdasd

返回信息

{
    "data": {
        "access_token": "du.2svbvjn82ycx5weh54slfbuebmn6im7o-3np7vpbklx-0zxzdhk-fkzgcpc84",
        "expires_in": 1541656437269,
        "refresh_token": "rt.99oz60qc8hn1jfwp9ml4nttid9u3w9h0-8s2wqprgxs-0zhci16-sssvtcmdk",
        "openId": "b4a3edff6af84a71b8a12912094359b5",
    },
    "code": "200",
    "msg": "操作成功"
}

返回字段

返回码

通过开发者appKey和appSecret获取设备托管ALL权限token

功能说明 该接口主要是开发者通过appKey和appSecret获取设备托管权限token, 该token主要是获取账户下所有被托管的设备,来源是多个C用户

请求地址 https://open.ys7.com/api/lapp/trust/device/v2/token/get

请求参数

请求报文

POST /trust/device/token/get HTTP/1.1
Host: openauth.ys7.com
Content-Type: application/x-www-form-urlencoded
appKey =sadasdasdasdadas &appSecret =dshfksdhf

返回信息

{
    "data": {
        "accessToken": "da.3q98ktuz49rerl7ebfewu7br07ove6y9-4u8opzpclp-1rwgjkn-zyy52a5vn",
        "expireTime": 1553851609869
    },
    "code": "200",
    "msg": "操作成功!"
}

返回字段:

返回码

获取设备托管列表

功能说明 该接口主要是用来获取授权托管给开发者的设备列表

请求地址 https://open.ys7.com/api/lapp/trust/device/list

请求参数

请求报文

POST /api/lapp/trust/device/list HTTP/1.1    
Host: open.ys7.com
Content-Type: application/x-www-form-urlencoded
access_token =du.dunwhxt2azk02hcn7phqygsybbw0wv6p& pageStart=1&pageSize=2

返回信息

{
    "page": {
        "total": 1,
        "page": 0,
        "size": 10
    },
    "data": [
        {
            "deviceSerial": "210699125",
            "deviceName": "C2W(210699125)1()3~",
            "cameraName": "C2W(210699125)1()3~",
            "channelNo": 1,
    “customName”:”客厅东北角”
            “deviceTrustId”:”test12334rw”
        }
    ],
    "code": "200",
    "msg": "操作成功!"
}

返回字段

返回码：