申请和使用许可证

许可证介绍Copy Anchor Link

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

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

使用流程Copy Anchor Link

1. 申请许可证Copy Anchor Link

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

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

2. 获取预授权Copy Anchor Link

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

3. 激活许可证Copy Anchor Link

完成预授权后，调用 activate 接口激活 License。

接口原型Copy Anchor Link

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

请求参数Copy Anchor Link

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

请求示例Copy Anchor Link

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

curl --location -X POST 'https://api.sd-rtn.com/dabiz/license/v2/active?pid=02F5xxxxxxxxxxxxxxxxxxxxxxxxEC30&licenseKey=xxxx&appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e' \
--header 'Authorization: Basic <Basic Auth>'

响应参数Copy Anchor Link

响应示例Copy Anchor Link

请求成功的响应示例：

{
  "code": 200,
  "data": {
    "pid": "E4D6xxxxxxxxxxxxxxxxxxxxxxxx7E79",
    "license": "1D65xxxxxxxxxxxxxxxxxxxxxxxx6016",
    "licenseKey": "1234xxxxxxxxxxx1234",
    "expireTime": 17xxxxxxxx,
    "activationTime": 17xxxxxxxx,
    "skuView": {
      "product": 1,
    }
  }
}

4. 使用许可证Copy Anchor Link

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

操作步骤如下：

1. 从服务端接收已激活的 License。

2. 写入 License，确保每个设备中写入的 License 是正确且唯一的。常见的两种写入方式如下，你可以根据实际需求自行实现：

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

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

3. 设备读取 License：

   • 如果读取成功，则进行下一步。
   • 如果读取失败，则返回步骤 2 排查问题。

4. 在 RTSA SDK 中，调用 agora_rtc_init``init 并在 rtc_service_option_t``RtcServiceOptions 的 license_value``licenseValue 参数中传入 License。

5. RTSA SDK 会在用户加入频道时自动验证 License。

   • 如果 License 验证成功，则用户可以正常使用 SDK 的功能。
   • 如果 License 验证失败，则用户会被踢出频道并收到 on_license_validation_failure``onLicenseValidationFailure 回调，你可以根据收到的错误码处理问题。

5. 查询即将到期的许可证列表Copy Anchor Link

能正常使用 License 后，你可以调用 expiringLicense 接口查询即将到期的 License 列表。

接口原型Copy Anchor Link

• 方法：GET
• 接入点：https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses

路径参数Copy Anchor Link

查询参数Copy Anchor Link

请求示例Copy Anchor Link

curl --location 'https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/pids/{pid}/expiringLicenses?expiringDay=90&size=10&page=1' \
--header 'Authorization: Basic <Basic Auth>'

响应参数Copy Anchor Link

响应示例Copy Anchor Link

请求成功的响应示例：

{
  "code": 200,
  "data": {
    "count": 1,
    "list": [
      {
        "license": "698AxxxxxxxxxxxxxxxxxxxxxxxxEDDB0",
        "licenseKey": "xxxx",
        "activeTime": "2024-12-02T08:15:39Z",
        "expireTime": "2024-12-05T08:15:39Z"
      }
    ]
  }
}

6. 许可证续期Copy Anchor Link

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

接口原型Copy Anchor Link

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

请求参数Copy Anchor Link

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

请求示例Copy Anchor Link

curl --location -X POST 'https://api.sd-rtn.com/dabiz/license/v2/renew?appid=a6d6xxxxxxxxxxxxxxxxxxxxxxxxf75e&renewId=4750xxxxxxxxxxxxxxxxxxxxxxxx6270&license=85B3xxxxxxxxxxxxxxxxxxxxxxxx656F' \
--header 'Authorization: Basic <Basic Auth>'

响应参数Copy Anchor Link

响应示例Copy Anchor Link

请求成功的响应示例：

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

7. 查询许可证续期订单Copy Anchor Link

该方法可以查询指定 PID 下所有的续期订单，方便用户根据剩余数量和有效期等信息，确定使用哪一个 renewId 进行续期。

接口原型Copy Anchor Link

• 方法：GET
• 接入点：https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/renewals

路径参数Copy Anchor Link

查询参数Copy Anchor Link

请求示例Copy Anchor Link

curl --location 'https://api.sd-rtn.com/dabiz/license/v3/projects/{appId}/renewals?size=10&page=1 \
--header 'Authorization: Basic <Basic Auth>'

响应参数Copy Anchor Link

响应示例Copy Anchor Link

请求成功的响应示例：

{
  "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"
      }
    ]
  }
}

参考信息Copy Anchor Link

RESTful API 基本信息Copy Anchor Link

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

域名Copy Anchor Link

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

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

认证方式Copy Anchor Link

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

调用频率限制Copy Anchor Link

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

域名切换Copy Anchor Link

切换域名的操作如下：

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 重试。

注意事项Copy Anchor Link

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

域名信息Copy Anchor Link

概念区分Copy Anchor Link

licenseValue 和 licenseKeyCopy Anchor Link

licenseValue

licenseValue 是每个 License 的标识。

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

licenseKey

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

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

测试许可证和正式许可证Copy Anchor Link

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

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

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

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