更新时间:2024-05-09 GMT+08:00

按需使用量推送(旧)

接口说明

用户在云商店开通按需资源并产生使用量后,ISV需通过此接口返回用户的实际使用量话单,云商店获取话单后根据使用量计费并对用户扣费。

SDK请参考《获取SDK》

如何获取AK/SK请参考《AK/SK认证说明》

URI

POST https://mkt-intl.myhuaweicloud.com/rest/marketplace/v1/isv/usage-data(公网)

请求消息

请求参数说明请参见下表:

请求方法:POST

参数

是否必选

类型

最大字符长度

说明

usage_records

List<UsagePushData>

1000

业务使用量纪录集合,UsagePushData个数不得超过1000。

表1 UsagePushData

参数

是否必选

参数类型

最大字符长度

描述

instance_id

String

64

按需实例ID(注意:使用按需接口返回的)

product_id

String

64

产品实例对应的产品id

record_time

String

17

使用量记录生成时间(UTC),格式为:

yyyyMMdd'T'HHmmss'Z'

begin_time

String

17

计量开始时间(UTC),格式为:

yyyyMMdd'T'HHmmss'Z'

end_time

String

17

计量结束时间(UTC),格式为:

yyyyMMdd'T'HHmmss'Z'

usage_value

Double(12,4)

20

使用量具体值,最多支持4位有效小数,需要大于是0的数值

relate_pkg_instance

String

64

用完即停套餐包场景下话单必传,需要传递当前用量对应的扣减包实例ID

请求消息示例:

{ 
    "usage_records": [ 
        { 
            "instance_id": "7f141bf1-aec8-4859-8323-fb3a8ad50721", 
            "record_time": "20220809T091000Z", 
            "begin_time": "20220809T080000Z", 
            "end_time": "20220809T090000Z", 
            "usage_value": "99" 
        }, 
        { 
            "instance_id": "7f141bf1-aec8-4859-8323-fb3a8ad50721", 
            "record_time": "20220809T091000Z", 
            "begin_time": "20220809T080000Z", 
            "end_time": "20220809T090000Z", 
            "usage_value": "999" 
        } 
    ] 
}

1、接口调用上传时,如果话单数据异常,不会在接口层进行报错;后台定时任务会对上传的数据进行校验和处理,生成可以使用的话单数据。如果后台数据处理失败,需要商家重新进行上报。

异常数据可以在 “卖家中心>交易管理>话单管理” 进行查看!

2、话单上报周期要求:

  • 按小时计费

    需要至少每小时上报一次话单数据,且最好在消费时间下一个小时的0-15分钟内完成上报,譬如,用户消费时间在13:25,最好在14:00-14:15内上报,这样能及时给用户扣费,否则就会出现扣费延迟,如果无法实现实时上报,需要在2小时完成上报

  • 按天计费

    推荐每小时将已经明确的用量话单上报到云商店,如果必须每天汇总上报一次,需要保证必须在次日的00:00-00:15内完成上报,最大不能超过01:00,否则用户的扣费会延迟到下一天

3、话单数据上报要求:

  • 资源未关闭
    • 话单开始时间(begin_time)≥资源开始时间
    • 话单开始时间(begin_time)≤话单结束时间(end_time)≤ 话单上报时间
  • 资源关闭后:
    • 话单结束时间(end_time)≤资源关闭时间

4、话单上报中的时间为UTC 时间,与北京时间相差 8 小时;

5、同一个记录的时间,即begin_time 和end_time 时间都一致的情况下,如多次上报记录,会被识别为重复话单,只会处理一条数据,一旦话单采集后形成正式账单将无法逆向错误话单(话单采集时间:按天计费为每天凌晨1点,按小时计费为每小时15分)。

  • 6、使用量推送接口使用按需接口返回的实例ID,不能使用套餐包返回的实例ID。

响应消息

响应参数说明请参见下表:

参数

是否必选

类型

最大字符长度

说明

error_code

M

String

6

调用结果码。

具体请参见下方错误码参数说明。

error_msg

O

String

255

调用结果描述。

错误码参数说明请参见下表:

http状态码

error_code

error_msg

描述

200

MKT.0000

Success.

请求成功

500

MKT.0999

System internal error.

其它服务内部错误

500

MKT.0100

Failure of input parameter

输入参数校验失败

参数范围超限,非法值或格式错误

400

MKT.0101

Invalid parameter

参数无效

输入非接口定义的参数,多参数或少必选参数

400

MKT.0102

Invalid body sign

请求body体签名校验失败

400

MKT.0199

Request parameter error

请求参数错误

其它参数错误

401

MKT.0150

Illegal operation

通常是进行了不被授权的操作,例如instance_id对应的产品不是AK/SK对应的ISV发布的

401

MKT.0151

No authority

无API访问权限

token非ISV角色

401

MKT.0154

Illegal token

鉴权失败

token无效

500

MKT.9001

Instance ID not found.

实例ID不存在(商品续费、过期、资源释放接口可能返回)

500

MKT.9002

Invalid usage enties.

计量实体无效

500

MKT.9003

Usage records extends size limit.

计量记录数超出限制(1000条)

500

MKT.9004

Record beginTime extends Limit.

计量记录的起始时间超出有效期(当前时间21天以内)

当您调用API时,如果遇到“APIGW”开头的错误码,请参见API网关错误码进行处理。

响应消息示例:

{ 
   "error_code":"MKT.0000", 
   "error_msg":"success" 
}