2024/05/27 11:27:07

申请和使用 License

License 介绍

License 是声网服务的一种计费模式。在 IoT 场景中，声网通过设备 License 对单个设备进行收费，每个设备的 License 是唯一的。在 License 有效期内，不再对通话时长进行收费。

通常 IoT 厂商会预估设备的出货量与音视频用量，向声网采购 License 并激活，再以一机一码的形式将 License 烧录在设备中。下图展示了设备 License 的整体使用流程：

License 使用流程

1. License 申请

声网为每位开发者提供 10 个有效期为 6 个月的免费测试 License。如需申请使用 License，联系 sales@shengwang.cn 并提供以下信息：

名称	说明
品类	License 的品类：设备 License，用于绑定设备。
企业 ID (CID)	声网分配给每个企业 (组织) 的唯一标识。你可以注册账号并在控制台的账号设置页面获取 CID。
License 类型	License 的类型：测试 License 正式 License 信息声网推荐你在集成测试时选用测试 License，正式上线前改用正式 License。详见测试 License 和正式 License。
库存量单位 (SKU)	设置 License 的能力集，包含以下参数：产品：媒体流加速 (RTSA)。 License 能力：音频。视频。音视频。 License 分钟数上限：是否限制使用时长，精确到分钟。 License 使用时间段：是否限制使用时段，精确到分钟。
有效期	License 的有效期：测试 License 的有效期以天为单位，最少 3 天。正式 License 的有效期以年为单位，最少 1 年。 License 的有效期从激活当日开始计算。
申请数量	申请的 License 数量。
启用 License 的项目 ID (App ID) 列表	App ID 为声网分配给每个项目的唯一标识，从属于 CID。你可以为指定 App ID 启用 License 功能。你可以创建项目并在控制台的项目管理页面获取 App ID。
是否设置最高同时在线人数 (PCU) 限制	启用 PCU 限制后，你可以限制 CID 或 App ID 维度上同时接入 SDK 的最大人数。

License 申请通过后，License PID 会关联到你的 CID 下，你可以在控制台的 License 用量页面查看 License 的 PID 和使用情况。

2. License 预授权

为保障 License 的安全性，降低被盗用的风险，声网提供预授权功能。你需要向 sales@shengwang.cn 提供项目 App ID 和 licenseKey 进行预授权，将设备加入白名单。预授权完成后，License 额度会被消耗，只有白名单中的设备才能通过校验激活 License。

3. License 激活

完成预授权后，参考本节信息和 RESTful API 基本信息调用 RESTful API 激活 License。

接口原型

方法：POST
接入点：https://api.sd-rtn.com/dabiz/license/v2/active

请求参数

在请求路径中传入以下查询参数：

参数	类型	描述
`pid`	String	由 SKU、有效期、品类定义的 License 激活标识。
`licenseKey`	String	设备的唯一标识。例如设备的 SN 号、Mac 地址等。字符串长度需小于 64 字节。信息请注意区分大小写。只有在白名单中的 licenseKey 才能通过校验激活 License。
`appid`	String	App ID，声网分配给每个项目的唯一标识。

请求示例

在请求路径中传入查询参数的示例如下：

HTTP
https://api.sd-rtn.com/dabiz/license/v2/active?pid=02F5xxxxxxxxxxxxxxxxxxxxxxxxEC30&licenseKey=xxxx&appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e

响应参数

200
其他

请求成功。响应包体中包含如下参数：

参数类型描述

参数	类型	描述
`license`	String	激活的 License 的值。信息你需要自行保存该值，以便后续进行续期等操作。
`skuView`	Array	SKU 能力集： `product`(Integer): `1`: RTC `2`: RTSA `3`: FPA `name` (String): SKU 的名称 `mediaType`(Integer): `1`: 音频 `2`: 视频 `3`: 音视频 `minutes` (Integer): License 分钟数上限 `period` (String): License 使用时间段

license

String

激活的 License 的值。

信息

你需要自行保存该值，以便后续进行续期等操作。

skuView

Array

SKU 能力集：

product(Integer):
- 1: RTC
- 2: RTSA
- 3: FPA
name (String): SKU 的名称
mediaType(Integer):
- 1: 音频
- 2: 视频
- 3: 音视频
minutes (Integer): License 分钟数上限
period (String): License 使用时间段

请求失败。你可以根据返回的状态码和响应包体中 message 字段的描述排查错误。

响应示例

请求成功的响应示例：

JSON
{
    "code": 200,
    "data": {
        "license": "1D65xxxxxxxxxxxxxxxxxxxxxxxx6016",
        "skuView": {
            "product": 1,
            "name": "演示申请01",
            "mediaType": 1,
            "minutes": 100,
            "period": "00:00~23:59"
        }
    }
}

4. License 使用

成功激活 License 后，你需要在 SDK 中使用 License 并在设备中烧录 License，流程图如下：

操作步骤如下：

从服务端接收已激活的 License。
写入 License，确保每个设备中写入的 License 是正确且唯一的。常见的两种写入方式如下，你可以根据实际需求自行实现：

信息

请注意区分 License 值的大小写。

写入文件中，通过程序让设备读取。
在设备出厂时烧写入设备中，设备在本地文件中读取。

信息

请注意区分 License 值的大小写。

设备读取 License：
- 如果读取成功，则进行下一步。
- 如果读取失败，则返回步骤 2 排查问题。
在 RTSA SDK 中，调用 init 并在 RtcServiceOptions 的 licenseValue 参数中传入 License。
RTSA SDK 会在用户加入频道时自动验证 License。
- 如果 License 验证成功，则用户可以正常使用 SDK 的功能。
- 如果 License 验证失败，则用户会被踢出频道并收到 onLicenseValidationFailure 回调，你可以根据收到的错误码处理问题。

5. License 续期

如需继续使用声网服务，为不影响你的业务，声网推荐你至少在 License 到期前 30 天联系 sales@shengwang.cn 申请续期。续期申请通过后，声网会生成 renewId 并提供给你，你可以参考本节信息和 RESTful API 基本信息调用 RESTful API 续期 License。

接口原型

方法：POST
接入点：https://api.sd-rtn.com/dabiz/license/v2/renew

请求参数

在请求路径中传入以下查询参数：

参数	类型	描述
`appid`	String	声网分配给每个项目的唯一标识。
`renewId`	String	（可选）由 SKU、有效期、品类定义的 License 续期标识。联系 sales@shengwang.cn 获取。如果不填，则声网会按照项目级别、公司级别从高到低优先选择最早生成的 `renewId` 来执行续期操作。
`license`	String	需要续期的 License 值。你可以在激活接口的 `license` 响应参数中获取。信息请注意区分大小写。

信息

请注意区分 License 值的大小写。
为避免误调用续期 API 引起不必要的损失，只有当 License 的剩余有效时间小于 renewId 的有效期时，你才能成功调用续期 API。例如，当 License 的剩余有效时间为 40 天时，如果 renewId 的有效期为 60 天，则你可以成功调用续期 API；如果 renewId 的有效期为 30 天，则调用续期 API 会失败。

请求示例

请求路径

HTTP
https://api.sd-rtn.com/dabiz/license/v2/renew?appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e&renewId=4750xxxxxxxxxxxxxxxxxxxxxxxx6270&license=85B3xxxxxxxxxxxxxxxxxxxxxxxx656F

响应参数

200
其他

请求成功。响应包体中包含如下参数：

参数	类型	描述
`licenseKey`	String	设备的唯一标识。
`license`	String	续期的 License。
`renewTimes`	Int	续期次数。
`lastRenewTime`	Int	上次续期的时间戳。
`activationTime`	Int	License 激活的时间戳。
`expireTime`	Int	License 过期的时间戳。

请求失败。你可以根据返回的状态码和响应包体中 message 字段的描述排查错误。

响应示例

请求成功的响应示例：

JSON
{
    "code": 200,
    "message": "license续期成功",
    "data":{
        "licenseKey":"xxxx",
        "license":"85B3xxxxxxxxxxxxxxxxxxxxxxxx656F",
        "renewTimes":1,
        "lastRenewTime":1700644272,
        "activationTime":1700642665,
        "expireTime":1705913065,
    }
}

相关信息

RESTful API 基本信息

本节介绍所有声网控制台 RESTful API 基本信息。

域名

所有请求都发送给域名：api.sd-rtn.com。

为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供切换域名的方案。详见切换域名。

认证方式

声网控制台 RESTful API 仅支持 HTTPS 协议。发送请求时，你需要使用声网提供的客户 ID 和客户密钥生成一个 Base64 算法编码的凭证，并填入 HTTP 请求头部的 Authorization 字段中。详见如何在 RESTful API 中进行 HTTP 基本认证和 Token 认证。

调用频率限制

对于每个声网账号（非每个 App ID），本页每个 API 的调用频率上限为每秒 10 次。如果调用频率超出限制，参考如何处理服务端 RESTful API 调用超出频率限制优化调用频率。

域名切换

为保障 REST 服务的高可用，避免因区域网络故障造成的服务不可用，声网提供切换域名的方案。

切换域名操作：

根据你的业务服务器所在地设置主域名：
- 业务服务器 DNS 地址位于中国大陆时，设置主域名为 api.sd-rtn.com。
- 业务服务器 DNS 地址位于中国大陆以外的国家或地区时，设置主域名为 api.agora.io。
当使用主域名发起 RESTful API 请求失败时，使用该域名重试一次。
如果步骤 2 的重试依然失败，使用备用的主域名重试：
- 如果当前设置的主域名为 api.sd-rtn.com，备用的主域名指 api.agora.io。
- 如果当前设置的主域名为 api.agora.io，备用的主域名指 api.sd-rtn.com。
如果步骤 3 的重试依然失败，使用与当前解析区域相邻的区域域名重试。举例说明：假设你的业务服务器位于欧洲，你设置主域名为 api.agora.io，而且业务服务器解析主域名解析到德国。德国位于欧洲中部 api-eu-central-1.agora.io，查域名信息表可知，相邻区域为欧洲西部 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com。因此，出现网络故障且步骤 2、3 的重试失败时，请使用 api-eu-west-1.agora.io 或 api-eu-west-1.sd-rtn.com 域名重试。

注意事项：

为避免重试请求过于频繁，超过声网服务所规定的 QPS（每秒请求数），声网建议你使用退避策略。例如，第一次等待 1 秒后重试、第二次等待 3 秒后重试、第三次等待 6 秒后重试。
如果是网络问题而非 DNS 解析域名问题导致的请求失败，声网建议你跳过步骤 3，直接进行步骤 4。
切换至区域域名前，请确保你使用的业务（例如，云端录制、云信令、频道管理等 REST 服务）在该区域有部署服务。

域名信息：

主域名	区域域名	地理区域
api.sd-rtn.com	api-us-west-1.sd-rtn.com	美国西部
	api-us-east-1.sd-rtn.com	美国东部
	api-ap-southeast-1.sd-rtn.com	亚太东南
	api-ap-northeast-1.sd-rtn.com	亚太东北
	api-eu-west-1.sd-rtn.com	欧洲西部
	api-eu-central-1.sd-rtn.com	欧洲中部
	api-cn-east-1.sd-rtn.com	中国华东
	api-cn-north-1.sd-rtn.com	中国华北
api.agora.io	api-us-west-1.agora.io	美国西部
	api-us-east-1.agora.io	美国东部
	api-ap-southeast-1.agora.io	亚太东南
	api-ap-northeast-1.agora.io	亚太东北
	api-eu-west-1.agora.io	欧洲西部
	api-eu-central-1.agora.io	欧洲中部
	api-cn-east-1.agora.io	中国华东
	api-cn-north-1.agora.io	中国华北

概念区分

licenseValue 和 licenseKey

信息

在使用 licenseValue 或 licenseKey 时，请注意区分大小写。

licenseValue

licenseValue 是每个 License 的标识。

用户申请续期时，要提供指定 License 的 licenseValue。你可以在激活接口的 license 响应参数获取 licenseValue。

licenseKey

licenseKey 是设备的唯一标识。例如设备的 SN 号、Mac 地址等。字符串长度需小于 64 字节。

用户需要先进行预授权，将设备的 licenseKey 添加到白名单，然后才能调用激活接口为某个设备激活 License。

测试 License 和正式 License

为方便你测试和使用 SDK，声网提供测试 License 和正式 License，区别如下：

测试 License：用于集成测试、产品调试阶段。
正式 License：用于产品正式上线阶段。

声网推荐你先使用测试 License，在产品正式上线前，参考如下步骤改用正式 License：

联系 sales@shengwang.cn 申请正式 License（下称“新 License”）。License 申请成功后在 License 用量页面查看 License 的 PID。
调用激活接口激活新的 License，在激活接口中传入新 License 的 PID、与老 License 一致的 licenseKey。
在设备中写入并读取新的 License。
在 SDK 中，调用 init 并在 RtcServiceOptions 的 licenseValue 参数中传入新的 License。

License 介绍​

License 使用流程​

1. License 申请​

2. License 预授权​

3. License 激活​

接口原型​

请求参数​

请求示例​

响应参数​

响应示例​

4. License 使用​

5. License 续期​

接口原型​

请求参数​

请求示例​

响应参数​

响应示例​

相关信息​

RESTful API 基本信息​

域名​

认证方式​

调用频率限制​

域名切换​

概念区分​

licenseValue 和 licenseKey​

测试 License 和正式 License​

License 介绍

License 使用流程

1. License 申请

2. License 预授权

3. License 激活

接口原型

请求参数

请求示例

响应参数

响应示例

4. License 使用

5. License 续期

接口原型

请求参数

请求示例

响应参数

响应示例

相关信息

RESTful API 基本信息

域名

认证方式

调用频率限制

域名切换

概念区分

licenseValue 和 licenseKey

测试 License 和正式 License