服务商将插件发布在声网云市场前,需要实现一套计量计费的 RESTful API,并将对应的 URL 地址提供给声网。声网会定期调用这套 API,向服务商获取指定计量和计费相关信息,并通知到使用插件的开发者。
实现计量计费 RESTful API时,请确保你的服务器满足如下要求:
每次调用后,声网服务器会等待 500 毫秒。如果等待期内没有收到响应信息,会再次调用接口。重复调用达到三次将会停止调用。
开发者在声网控制台项目中启用插件后,声网会每天调用一次该 API 获取插件用量,将获取的用量求和并向上求整,然后更新控制台界面的用量信息。
请求 URL
GET https://{host}/usage?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}
查询参数
参数 | 是否必需 | 类型 | 数据长度 | 描述 |
---|---|---|---|---|
fromTs |
必需 | 时间戳 | 10 | 要查询的时间段的起点,必须在当天 UTC 时间的 0 点之后。 |
toTs |
必需 | 时间戳 | 10 | 要查询的时间段的终点,必须在当天 UTC 时间的 23:59:59 之前。 |
pageNum |
必需 | Int | N/A | 用量列表的页数,表示查询第几页的用量。你需要对用量列表进行分页设置,并在响应参数的 hasNext 字段中返回是否还有下一页。声网在每天第一次调用该方法时,会始终将该参数设为 1,并在收到响应后重复调用该方法,直到响应参数中的 hasNext 字段返回 false 。 |
limit |
可选 | Int | N/A | 每次响应最多包含多少条数据。请确保你为该字段设置了一个默认值。 |
apiKey |
必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
signature |
必需 | String | N/A | 通过签名算法生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
status |
Int | 请求的状态码。0 表示请求成功。 |
statusReason |
String | 状态对应的原因。 |
totalSize |
Int | 已启用插件的项目总数。 |
pageNum |
Int | 用量列表的第几页。该字段需要和请求中的 pageNum 字段一致。 |
hasNext |
Boolean | 用量列表是否还有下一页:
|
data |
Array | 用量信息,包含如下数据:
projectId 为空或者 amount 为 0 的数据不需要返回。 |
请求行
GET https://{host}/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
响应包体
{
"status": 0,
"statusReason": "Success getting usage data",
"data": {
"totalSize": 2,
"pageNum": 2,
"hasNext": false,
"data": [
{
"projectId": "4****2",
"amount": 1,
"description": "1 分钟 × 声网云市场单价 (¥***/月)"
}
]
}
}
开发者在声网控制台项目中启用插件后,声网会在每个月末调用该 API 获取使用插件产生的计费信息,将每次请求获取到的费用相加后向上取整,然后更新控制台界面的计费信息。
请求 URL
GET https://{host}/bill?fromTs={ts}&toTs={ts}&pageNum={pageNum}&apiKey={apiKey}&signature={signature}
查询参数
参数 | 是否必需 | 类型 | 数据长度 | 描述 |
---|---|---|---|---|
fromTs |
必需 | 时间戳 | 10 | 要查询的时间段的起点,必须在当月第一天的 UTC 时间 0 点之后。 |
toTs |
必需 | 时间戳 | 10 | 要查询的时间段的终点,必须在当月最后一天的 UTC 时间 23:59:59 之前。 |
pageNum |
必需 | Int | N/A | 用量列表的页数,表示查询第几页的用量。你需要对用量列表进行分页设置,并在响应参数的 hasNext 字段中返回是否还有下一页。声网在每天第一次调用该方法时,会始终将该参数设为 1,并在收到响应后重复调用该方法,直到响应参数中的 hasNext 字段返回 false 。 |
limit |
可选 | Int | N/A | 每次响应最多包含多少条数据。请确保你给该字段设置了一个默认值。 |
apiKey |
必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
signature |
必需 | String | N/A | 通过签名算法生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
status |
Int | 请求的状态码。0 表示请求成功。 |
statusReason |
String | 状态对应的原因。 |
totalSize |
Int | 已启用插件的项目总数。 |
pageNum |
Int | 费用列表的第几页。该字段需要和请求中的 pageNum 字段一致。 |
hasNext |
Boolean | 费用列表是否还有下一页:
|
data |
Array | 费用信息,包含如下数据:
projectId 为空或者 amount 为 0 的数据不需要返回。 |
请求行
GET https://{host}/usage?fromTs=1619913600&toTs=1619917200&pageNum=1&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
响应示例
{
"status": 0,
"statusReason": "Success getting billing data",
"data": {
"totalSize": 2,
"pageNum": 2,
"hasNext": false,
"data": [
{
"projectId": "4xxxx2",
"amount": 1,
"description": "1 分钟 × 声网云市场单价 (¥***/月)"
}
]
}
}
该方法获取指定开发者的 license 信息。如果你使用授权 license 的方式进行计费,声网会在需要时调用该方法获取指定 license 的有效期和剩余次数。
请求 URL
GET https://{host}/customers/{customerId}/license&apiKey={apiKey}&signature={signature}
路径参数
参数 | 是否必需 | 类型 | 数据长度 | 描述 |
---|---|---|---|---|
customerId |
必需 | String | N/A | 开发者在声网控制台注册的账户 ID。 |
apiKey |
必需 | String | 32 | 你的 API Key,用于和声网之间的鉴权。你需要向声网提供自行生成的 API Key。 |
signature |
必需 | String | N/A | 通过签名算法生成的签名。你需要自己部署签名算法,以确认该请求是声网发送的。 |
响应包体中包含以下字段:
字段 | 类型 | 描述 |
---|---|---|
status |
String | 请求状态:success : 请求成功。failed : 请求失败。 |
statusReason |
String | 状态对应的原因。 |
expireDate |
String | 开发者的 license 过期时间。 |
residueCount |
String | license 剩余次数。 |
请求行
GET https://{host}/customers/1xxxx6/license&apiKey=pz*************gd&signature=Q7**************************Sa HTTP/1.1
响应包体
{
"status": "success",
"statusReason": "",
"data": {
"expireDate": "2025-10-01",
"residueCount": "100"
}
}