# 申请和使用 License (/zh-CN/realtime-media/rtsa/build/project-preparation/license) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). ## License 介绍 [#license-介绍] License 是声网服务的一种计费模式。在 IoT 场景中,声网通过设备 License 对单个设备进行收费,每个设备的 License 是唯一的。在 License 有效期内,不再对通话时长进行收费。 通常 IoT 厂商会预估设备的出货量与音视频用量,向声网采购 License 并激活,再以一机一码的形式将 License 烧录在设备中。下图展示了设备 License 的整体使用流程: ![license workflow](https://web-cdn.agora.io/docs-portal/img/rtsa/license.svg) ## 使用流程 [#使用流程] ### 1. 申请 License [#1-申请-license] 声网为每位开发者提供 10 个有效期为 6 个月的免费测试 License。如需申请使用 License,联系 sales@shengwang.cn 并提供以下信息: | 名称 | 说明 | | --- | --- | | 品类 | License 的品类:设备 License,用于绑定设备。 | | 企业 ID (CID) | 声网分配给每个企业 (组织) 的唯一标识。你可以[注册账号](/zh-CN/introduction/quickstart#注册账号)并在[控制台](https://console.shengwang.cn/settings/company)的账号设置页面获取 CID。 | | License 类型 | [license-html-0-3-1 details](#table-slot-license-html-0-3-1) | | 库存量单位 (SKU) | [license-html-0-4-1 details](#table-slot-license-html-0-4-1) | | 有效期 | [license-html-0-5-1 details](#table-slot-license-html-0-5-1) | | 申请数量 | 申请的 License 数量。 | | 启用 License 的项目 ID (App ID) 列表 | App ID 为声网分配给每个项目的唯一标识,从属于 CID。你可以为指定 App ID 启用 License 功能。你可以[创建项目](/zh-CN/introduction/quickstart#创建项目)并在[控制台](https://console.shengwang.cn/projects)的项目管理页面获取 App ID。 | | 是否设置最高同时在线人数 (PCU) 限制 | 启用 PCU 限制后,你可以限制 CID 或 App ID 维度上同时接入 SDK 的最大人数。 | **license-html-0-3-1 details** License 的类型: - 测试 License - 正式 License 声网推荐你在集成测试时选用测试 License,正式上线前改用正式 License。详见[测试 License 和正式 License](#licensetype)。 **license-html-0-4-1 details** 设置 License 的能力集,包含以下参数: - 产品: - 媒体流加速 (RTSA)。 - License 能力: - 音频。 - 视频。 - 音视频。 - License 分钟数上限:是否限制使用时长,精确到分钟。 - License 使用时间段:是否限制使用时段,精确到分钟。 **license-html-0-5-1 details** License 的有效期: - 测试 License 的有效期以天为单位,最少 3 天。 - 正式 License 的有效期以年为单位,最少 1 年。 License 的有效期从激活当日开始计算。 License 申请通过后,License 激活标识(PID) 会关联到你的 CID 下,你可以在[控制台](https://console.shengwang.cn/license/usage)的 License 用量页面查看 License 的 PID 和使用情况。 ### 2. 获取预授权 [#2-获取预授权] 为保障 License 的安全性、降低被盗用风险,声网提供预授权功能。可在声网控制台自行完成预授权。 1. 登录[声网控制台](https://console.shengwang.cn),进入 **License > 预授权**。 2. 选择需要预授权的 License PID,并按页面提示导入设备的唯一标识 `licenseKey`,例如设备 SN 号或 MAC 地址。 ![在控制台进行 License 预授权](https://web-cdn.agora.io/docs-portal/img/rtsa/preauthorization.png) 预授权完成后,设备会加入白名单并消耗相应的 License 额度。只有白名单中的设备才能通过校验并激活 License。 ### 3. 激活 License [#3-激活-license] 完成预授权后,调用 `activate` 接口激活 License。 #### 接口原型 [#接口原型] - 方法:`POST` - 接入点:`https://api.sd-rtn.com/dabiz/license/v2/active` #### 请求参数 [#请求参数] 在请求路径中传入以下查询参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `pid` | String | 由 SKU、有效期、品类定义的 License 激活标识。 | | `licenseKey` | String | [license-html-1-2-2 details](#table-slot-license-html-1-2-2) | | `appid` | String | App ID,声网分配给每个项目的唯一标识。 | **license-html-1-2-2 details** 设备的唯一标识。例如设备的 SN 号、Mac 地址等。字符串长度需小于 64 字节。 :::warning[注意] - 请注意区分大小写。 - 只有在白名单中的 `licenseKey` 才能通过校验激活 License。 ::: #### 请求示例 [#请求示例] 在请求路径中传入查询参数的示例如下: ```shell curl --location -X POST 'https://api.sd-rtn.com/dabiz/license/v2/active?pid=02F5xxxxxxxxxxxxxxxxxxxxxxxxEC30&licenseKey=xxxx&appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e' \ --header 'Authorization: Basic ' ``` #### 响应参数 [#响应参数] 200 其他 请求成功。响应 Body 中包含如下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `pid` | String | 由 SKU、有效期、品类定义的 License 激活标识。 | | `license` | String | [license-html-2-2-2 details](#table-slot-license-html-2-2-2) | | `licenseKey` | String | 设备的唯一标识。和你在 `activate` 接口中传入的 `licenseKey` 一致。 | | `expireTime` | String | License 的过期时间。 | | `activationTime` | String | License 的激活时间。 | | `skuView` | Array | [license-html-2-6-2 details](#table-slot-license-html-2-6-2) | **license-html-2-2-2 details** 激活的 License 的值。 :::info[信息] 你需要自行保存该值,以便后续进行续期等操作。 ::: **license-html-2-6-2 details** SKU 能力集,包含如下字段: - `product`(Integer): - `1`: RTC - `4`: 微呼叫 :::info[信息] 该参数下原有的 `mediaType`、`name`、`minutes` 和 `period` 字段不再有实际业务意义。 ::: 请求失败。你可以根据返回的[响应状态码](/zh-CN/api-reference/console/general/api/response-code)和响应 Body 中 `message` 字段的描述排查错误。 #### 响应示例 [#响应示例] 请求成功的响应示例: ```json { "code": 200, "data": { "pid": "E4D6xxxxxxxxxxxxxxxxxxxxxxxx7E79", "license": "1D65xxxxxxxxxxxxxxxxxxxxxxxx6016", "licenseKey": "1234xxxxxxxxxxx1234", "expireTime": 17xxxxxxxx, "activationTime": 17xxxxxxxx, "skuView": { "product": 1, } } } ``` ### 4. 使用 License [#4-使用-license] 成功激活 License 后,你需要在 SDK 中使用 License 并在设备中烧录 License,流程图如下: ![use license](https://web-cdn.agora.io/docs-portal/img/rtsa/use-license.png) 操作步骤如下: 1. 从服务端接收已激活的 License。 2. 写入 License,确保每个设备中写入的 License 是正确且唯一的。常见的两种写入方式如下,你可以根据实际需求自行实现: - 写入文件中,通过程序让设备读取。 - 在设备出厂时烧写入设备中,设备在本地文件中读取。 :::warning[注意] 请注意区分 License 值的大小写。 ::: 3. 设备读取 License: - 如果读取成功,则进行下一步。 - 如果读取失败,则返回步骤 2 排查问题。 4. 在 RTSA SDK 中,调用 `agora_rtc_init` 并在 `rtc_service_option_t` 的 `license_value` 参数中传入 License。 5. RTSA SDK 会在用户加入频道时自动验证 License。 - 如果 License 验证成功,则用户可以正常使用 SDK 的功能。 - 如果 License 验证失败,则用户会被踢出频道并收到 `on_license_validation_failure` 回调,你可以根据收到的错误码处理问题。 ### 5. 查询即将到期的 License 列表 [#5-查询即将到期的-license-列表] 能正常使用 License 后,你可以调用 `expiringLicense` 接口查询即将到期的 License 列表。 #### 接口原型 [#接口原型-1] - 方法:`GET` - 接入点:`https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses` #### 路径参数 [#路径参数] | 参数 | 类型 | 描述 | | ------- | ------ | ---------------------------------------------------------------------------------------- | | `appId` | String | 声网分配给每个项目的唯一标识。 | | `pid` | String | 由 SKU、有效期、品类定义的 License 激活标识。需要和 `activate` 接口中传入的 `pid` 一致。 | #### 查询参数 [#查询参数] | 参数 | 类型 | 描述 | | --- | --- | --- | | `page` | Int | (可选)分页页码。默认值为 1。 | | `size` | Int | (可选)每页查询的 License 数量。默认值为 100,最大值为 100。 | | `expiringLicenses` | Int | [license-html-3-3-2 details](#table-slot-license-html-3-3-2) | **license-html-3-3-2 details** 将要过期的天数,可设为如下值: - `60`: 60 天。 - `90`: 90 天。 服务器会返回即将在设置的天数内过期的 License 信息。不会返回已经过期的 License 信息。 #### 请求示例 [#请求示例-1] ```shell curl --location 'https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses?expiringDay=90&size=10&page=1' \ --header 'Authorization: Basic ' ``` #### 响应参数 [#响应参数-1] 200 其他 请求成功。响应 Body 中包含如下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `count` | Int | 即将过期的 License 数量。 | | `licenseInfos` | []object | [license-html-4-2-2 details](#table-slot-license-html-4-2-2) | **license-html-4-2-2 details** 由多组 Lisence 信息组成的数组,包含如下字段: - `licenseKey`: 设备的唯一标识。和你在 `activate` 接口中传入的 `licenseKey` 一致。 - `license`: 即将过期的 License 的值。 - `activeTime`: License 的激活时间,RFC3339 格式。 - `expireTime`: License 的过期时间,RFC3339 格式。 请求失败。你可以根据返回的[响应状态码](/zh-CN/api-reference/console/general/api/response-code)和响应 Body 中 `message` 字段的描述排查错误。 #### 响应示例 [#响应示例-1] 请求成功的响应示例: ```json { "code": 200, "data": { "count": 1, "list": [ { "license": "698AxxxxxxxxxxxxxxxxxxxxxxxxEDDB0", "licenseKey": "xxxx", "activeTime": "2024-12-02T08:15:39Z", "expireTime": "2024-12-05T08:15:39Z" } ] } } ``` ### 6. License 续期 [#6-license-续期] 如需继续使用声网服务,为不影响你的业务,声网推荐你至少在 License 到期前 30 天联系 sales@shengwang.cn 申请续期。续期申请通过后,声网会生成 `renewId` 并提供给你,你可以调用 `renew` 接口续期 License。 #### 接口原型 [#接口原型-2] - 方法:`POST` - 接入点:`https://api.sd-rtn.com/dabiz/license/v2/renew` #### 请求参数 [#请求参数-1] 在请求路径中传入以下查询参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `appid` | String | 声网分配给每个项目的唯一标识。 | | `renewId` | String | (可选)由 SKU、有效期、品类定义的 License 续期标识。联系 sales@shengwang.cn 获取。如果不填,则声网会按照项目级别、公司级别从高到低优先选择最早生成的 `renewId` 来执行续期操作。 | | `license` | String | [license-html-5-3-2 details](#table-slot-license-html-5-3-2) | **license-html-5-3-2 details** 需要续期的 License 值。你可以在[激活接口](#activate)的 `license` 响应参数中获取。 :::warning[注意] 请注意区分大小写。 ::: :::info[信息] 为避免误调用续期 API 引起不必要的损失,只有当 License 的剩余有效时间小于 `renewId` 的有效期时,你才能成功调用续期 API。例如,当 License 的剩余有效时间为 40 天时,如果 `renewId` 的有效期为 60 天,则你可以成功调用续期 API;如果 `renewId` 的有效期为 30 天,则调用续期 API 会失败。 ::: #### 请求示例 [#请求示例-2] ```shell curl --location -X POST 'https://api.sd-rtn.com/dabiz/license/v2/renew?appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e&renewId=4750xxxxxxxxxxxxxxxxxxxxxxxx6270&license=85B3xxxxxxxxxxxxxxxxxxxxxxxx656F' \ --header 'Authorization: Basic ' ``` #### 响应参数 [#响应参数-2] 200 其他 请求成功。响应 Body 中包含如下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `licenseKey` | String | 设备的唯一标识。 | | `license` | String | 续期的 License。 | | `renewTimes` | Int | 续期次数。 | | `lastRenewTime` | Int | 上次续期的时间戳。 | | `activationTime` | Int | License 激活的时间戳。 | | `expireTime` | Int | License 过期的时间戳。 | 请求失败。你可以根据返回的[响应状态码](/zh-CN/api-reference/console/general/api/response-code)和响应 Body 中 `message` 字段的描述排查错误。 #### 响应示例 [#响应示例-2] 请求成功的响应示例: ```json { "code": 200, "message": "license续期成功", "data": { "licenseKey": "xxxx", "license": "85B3xxxxxxxxxxxxxxxxxxxxxxxx656F", "renewTimes": 1, "lastRenewTime": 1700644272, "activationTime": 1700642665, "expireTime": 1705913065 } } ``` ### 7. 查询 License 续期订单 [#7-查询-license-续期订单] 该方法可以查询指定 PID 下所有的续期订单,方便用户根据剩余数量和有效期等信息,确定使用哪一个 `renewId` 进行续期。 #### 接口原型 [#接口原型-3] - 方法:`GET` - 接入点:`https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/renewals` #### 路径参数 [#路径参数-1] | 参数 | 类型 | 描述 | | ------- | ------ | ------------------------------ | | `appId` | String | 声网分配给每个项目的唯一标识。 | #### 查询参数 [#查询参数-1] | 参数 | 类型 | 描述 | | --- | --- | --- | | `pid` | String | (可选)由 SKU、有效期、品类定义的 License 激活标识。需要和 `activate` 接口中传入的 `pid` 一致。 | | `page` | Int | (可选)页码。默认值为 1。 | | `size` | Int | (可选)每页查询的 License 数量。默认值为 100,最大值为 100。 | #### 请求示例 [#请求示例-3] ```shell curl --location 'https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/renewals?size=10&page=1 \ --header 'Authorization: Basic ' ``` #### 响应参数 [#响应参数-3] 200 其他 请求成功。响应 Body 中包含如下参数: | 参数 | 类型 | 描述 | | --- | --- | --- | | `count` | Int | 续期订单数量。 | | `list` | []object | [license-html-8-2-2 details](#table-slot-license-html-8-2-2) | **license-html-8-2-2 details** 由多组续期订单信息组成的数组,包含如下字段: - `renewId`: 续期 ID。 - `pid`: 由 SKU、有效期、品类定义的 License 激活标识。和你在请求中填入的 `pid` 一致。 - `type`: License 类型: - `1`: 整个 CID 下所有 App ID 均可使用。 - `2`: 仅指定 App ID 可用。 - `duration`: 有效期。单位根据你的 `pid` 类型而定: - 如果 `pid` 为测试类型,则有效期的单位为天。 - 如果 `pid` 为正式类型,则有效期的单位为年。 - `totalCount`: 续期次数。 - `allocateCount`: 已经使用的次数。 - `createTime`: 续期创建的时间,RFC3339 格式。 请求失败。你可以根据返回的[响应状态码](/zh-CN/api-reference/console/general/api/response-code)和响应 Body 中 `message` 字段的描述排查错误。 #### 响应示例 [#响应示例-3] 请求成功的响应示例: ```json { "code": 200, "data": { "count": 2, "list": [ { "renewId": "xxxx", "pid": "xxxx", "type": 2, "duration": 50, "totalCount": 20, "allocateCount": 0, "createTime": "2024-12-02T08:32:12Z" }, { "renewId": "xxxx", "pid": "xxxx", "type": 1, "duration": 30, "totalCount": 100, "allocateCount": 0, "createTime": "2024-12-02T08:25:30Z" } ] } } ``` ## 参考信息 [#参考信息] ### RESTful API 基本信息 [#restful-api-基本信息] 本节介绍所有声网控制台 RESTful API 基本信息。 #### 域名 [#域名] 所有请求都发送给域名:`api.sd-rtn.com`。 为保障 REST 服务的高可用,避免因区域网络故障造成的服务不可用,声网提供切换域名的方案。详见[切换域名](#switchdomain)。 #### 认证方式 [#认证方式] 声网控制台 RESTful API 仅支持 HTTPS 协议。发送请求时,你需要使用声网提供的客户 ID 和客户密钥生成一个 Base64 算法编码的凭证,并填入 HTTP 请求 Header 的 `Authorization` 字段中。详见[实现 HTTP 基本认证](/zh-CN/realtime-media/rtc/build/setup-and-access/http-basic-auth)。 #### 调用频率限制 [#调用频率限制] 对于每个声网账号(非每个 App ID),本页每个 API 的调用频率上限为每秒 10 次。如果调用频率超出限制,参考[如何处理服务端 RESTful API 调用超出频率限制](/zh-CN/reference/faq/integration/restful_api_call_frequency)优化调用频率。 #### 域名切换 [#域名切换] 切换域名的操作如下: 1. 根据你的业务服务器所在地设置主域名: - 业务服务器 DNS 地址位于中国大陆时,设置主域名为 `api.sd-rtn.com`。 - 业务服务器 DNS 地址位于中国大陆以外的国家或地区时,设置主域名为 `api.agora.io`。 2. 当使用主域名发起 RESTful API 请求失败时,使用该域名重试一次。 3. 如果步骤 2 的重试依然失败,使用备用的主域名重试: - 如果当前设置的主域名为 `api.sd-rtn.com`,备用的主域名指 `api.agora.io`。 - 如果当前设置的主域名为 `api.agora.io`,备用的主域名指 `api.sd-rtn.com`。 4. 如果步骤 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] :::warning[注意] 在使用 `licenseValue` 或 `licenseKey` 时,请注意区分大小写。 ::: **licenseValue** `licenseValue` 是每个 License 的标识。 用户申请续期时,要提供指定 License 的 `licenseValue`。你可以在[激活接口](#activate)的 `license` 响应参数获取 `licenseValue`。 **licenseKey** licenseKey 是设备的唯一标识。例如设备的 SN 号、Mac 地址等。字符串长度需小于 64 字节。 用户需要先进行[预授权](#preauthenticate),将设备的 `licenseKey` 添加到白名单,然后才能调用[激活接口](#activate)为某个设备激活 License。 #### 测试 License 和正式 License [#测试-license-和正式-license] 为方便你测试和使用 SDK,声网提供测试 License 和正式 License,区别如下: - 测试 License:用于集成测试、产品调试阶段。 - 正式 License:用于产品正式上线阶段。 声网推荐你先使用测试 License,在产品正式上线前,参考如下步骤改用正式 License: 1. 联系 sales@shengwang.cn 申请正式 License(下称“新 License”)。License 申请成功后在 License 用量页面查看 License 的 PID。 2. 调用[激活接口](#activate)激活新的 License,在激活接口中传入新 License 的 PID、与老 License 一致的 `licenseKey`。 3. 在设备中写入并读取新的 License。 4. 在 SDK 中,调用 `agora_rtc_init` 并在 `rtc_service_option_t` 的 `license_value` 参数中传入新的 License。