Viewing Resource Usage Details

Function

This API can be used to query usage details of each resource for a customer on the self-built platform.

Postpaid customers who have enabled the monthly settlement can log in to Billing Center to query their resource usage details by referring to Resource Bill.

Constraints

This API can be invoked only by the customer AK/SK or token.

You can debug the API in API Explorer which supports automatic authentication. API Explorer can automatically generate and debug example SDK code.

URI

POST /v2/bills/customer-bills/res-records/query

Request Message

Request Parameters

Parameter	Mandatory	Type	Maximum Length	Description
cycle	Yes	String	8	Billing cycle of the queried resource usage details, which is in YYYY-MM format (GMT+08:00). Example: 2019-01 NOTE: Resource details generated before January 2019 are not supported.
cloud_service_type	No	String	64	Cloud service type code. For example, the cloud service type code of OBS is hws.service.type.obs. To obtain a specific service type, call the API in Querying Cloud Service Types. If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
resource_type	No	String	64	Resource type code. For example, the VM resource type code of ECS is hws.resource.type.vm. To obtain a specific resource type, call the API in Querying Resource Types. If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
region	No	String	64	Cloud service region code, for example, ap-southeast-1. Obtain the value from the Region column in Regions and Endpoints. If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
res_instance_id	No	String	64	Resource instance ID. If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
charge_mode	No	Integer	-	Billing mode. The options are as follows: 1: Yearly/monthly 3: Pay-per-use 10: Reserved instances 11: savings plan If this parameter is not included in the request parameters or is set to null, usage details of resources of all billing modes are returned.
bill_type	No	Integer	-	Bill type: 1: expenditure-purchase 2: expenditure-renewal 3: expenditure-change 4: refund-unsubscription 5: expenditure-use 8: expenditure-auto-renewal 9: adjustment-compensation 14: expenditure-month-end deduction for support plan 15: expenditure-tax 16: adjustment-deduction 17: expenditure-difference amount (min. guaranteed-actual) NOTE: Expenditure-difference amount (min. guaranteed-actual) determines the fees that a customer needs to pay if the customer does not reach the minimum expenditure limit stipulated in the signed contract. This rule is applicable to direct sales customers and referral customers who use postpaid method. 20: refund-change 23: savings plans used 24: Refund-changing to Pay-Per-Use 100: refund-unsubscription tax 101: adjustment-tax compensation 102: adjustment-tax deduction If this parameter is not included in the request parameters or is set to null, usage details of resources of all bill types are returned.
enterprise_project_id	No	String	64	Enterprise project ID. 0: ID of a default project – 1/null: Non-project ID. Non-project indicates that enterprise project management is not available for this cloud service. If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
include_zero_record	No	Boolean	-	Whether to return records for which the amount due is 0. true: Yes false: No If this parameter is not included in the request parameters, is set to "", or is set to null, it cannot be used as a filter criterion.
method	No	String	64	Query method. oneself: Query the resource usage details of an enterprise itself. sub_customer: Query the resource usage details of enterprise's sub-customers. all: Query the resource usage details of an enterprise and its sub-customers. If this parameter is not included in the request parameters, is set to "", or is set to null, the default value is all. If this parameter is set to all and an enterprise has no customers, the enterprise queries its own resource usage details.
sub_customer_id	No	String	64	Enterprise member account ID. NOTE: This parameter is invalid if method is not set to sub_customer. If method is set to sub_customer, this parameter must be specified.
offset	No	Integer	0- Maximum integer	Offset, which starts from 0. The default value is 0. NOTE: This parameter is used for pagination. Retain its default value 0 if pagination is not required. offset indicates the offset relative to the first data record among all that meets the conditions configured. If you set offset to 1, the second and subsequent data records are returned. For example, there are 10 data records, and if you set limit to 10 and offset to 1, the second to the tenth data records are returned.
limit	No	Integer	[1-1000]	Page limit. The default value is 10.
statistic_type	No	Integer	[1-2]	Statistics type. The default value is 1. 1: By billing cycle 2: By day If this parameter is not included in the request parameters or is set to null, the default value 1 is used. It cannot be set to "".
query_type	No	String	[0-9]	Type of information to be queried. The default value is BILLCYCLE. BILLCYCLE: By month DAILY: By day The information type, DAILY, is returned only when the statistic_type is set to 2. If this parameter is not included in the request or is set to null or "", the information type, BILLCYCLE, is returned by default.
bill_cycle_begin	No	String	[0-10]	The start time of a billing cycle. Format: YYYY-MM-DD. This parameter is mandatory when query_type is set to DAILY. If this parameter is not included in the request or is set to null or "", it cannot be used as a filter criterion. NOTE: This parameter is invalid if query_type is not set to DAILY. If query_type is set to DAILY, this parameter cannot be left empty and the month must be the same with the billing cycle.
bill_cycle_end	No	String	[0-10]	The end time of a billing cycle. Format: YYYY-MM-DD. This parameter is mandatory when query_type is set to DAILY. If this parameter is not included in the request or is set to null or "", it cannot be used as a filter criterion. NOTE: This parameter is invalid if query_type is not set to DAILY. If query_type is set to DAILY, this parameter cannot be left empty.

Example Request

POST https://bss-intl.myhuaweicloud.com/v2/bills/customer-bills/res-records/query HTTP/1.1
Content-Type: application/json
X-Auth-Token: MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ
{
      "cycle": "2018-12",
      "cloud_service_type": "hws.service.type.ec2",
      "resource_type": "hws.resource.type.vm",
      "region": "ap-southeast-1",
      "res_instance_id": "76*****7f",
      "charge_mode": 1,
      "bill_type": 1,
      "enterprise_project_id": "6***f3-3**4-4**2-9a3e-a****c24",
      "include_zero_record": "true",
       "method": "sub_customer",
       "sub_customer_id": "05b5fef62300d2ad0f98c00befba72c0",
      "offset": 1,
      "limit": 10
}

Response Message

Response Parameters

Parameter	Type	Maximum Length	Description
error_code	String	16	Status code. For details, see Status Code. This parameter is returned only when a failure occurs.
error_msg	String	1024	Error description. This parameter is returned only when a failure occurs.
monthly_records	List<MonthlyBillRes>	-	Resource records. For details, see Table 1.
total_count	Integer	-	Number of result sets. This parameter is returned only when the query is successful.
currency	String	3	Currency. USD

**Table 1** MonthlyBillRes
Parameter	Type	Maximum Length	Description
cycle	String	8	Billing cycle of resource data, which is in YYYY-MM format (GMT+08:00). Example: 2020-01
bill_date	String	10	Consumption date, which is in the YYYY-MM-DD format (GMT+08:00) NOTE: This parameter has a value only when statistic_type is set to 2. Otherwise, null is returned.
bill_type	Integer	-	Bill type. 1: expenditure-purchase 2: expenditure-renewal 3: expenditure-change 4: refund-unsubscription 5: expenditure-use 8: expenditure-auto-renewal 9: adjustment-compensation 14: expenditure-month-end deduction for support plan 15: expenditure-tax 16: adjustment-deduction 17: expenditure-difference amount (min. guaranteed-actual) NOTE: Expenditure-difference amount (min. guaranteed-actual) determines the fees that a customer needs to pay if the customer does not reach the minimum expenditure limit stipulated in the signed contract. This rule is applicable to direct sales customers and referral customers who use postpaid method. 20: refund-change 23: savings plans used 24: refund-changing to Pay-Per-Use 100: refund-unsubscription tax 101: adjustment-tax compensation 102: adjustment-tax deduction
customer_id	String	64	ID of the account that has consumption records. If a common account or enterprise member account is used to query consumption records, only the ID of the customer itself is displayed. If an enterprise master account is used to query consumption records, the consumption records of its own and its member accounts can be queried. The ID of a master or member account will be displayed.
region	String	64	Cloud service region code, for example, ap-southeast-1. Obtain the value from the Region column in Regions and Endpoints.
region_name	String	64	Region name, for example, CN-Hong Kong. Obtain the value from the Region column in Regions and Endpoints..
cloud_service_type	String	256	Cloud service type code. For example, the cloud service type code of OBS is hws.service.type.obs.
resource_Type_code	String	64	Resource type code. For example, the resource type code of ECS is hws.resource.type.vm.
cloud_service_type_name	String	200	Cloud service type. For example, the cloud service type of ECS is Elastic Cloud Server.
resource_type_name	String	200	Resource type. For example, the resource type of ECS is Cloud Host.
res_instance_id	String	256	Resource instance ID.
resource_name	String	-	Resource name. When creating a resource, a customer can enter the resource name. Some resource names can also be changed during resource management.
root_resource_id	String	-	Root resource ID
parent_resource_id	String	-	Parent resource ID
resource_tag	String	-	Resource tag. Customers can set tags when managing resources.
sku_code	String	64	SKU code, which uniquely identifies the resource specification in a bill.
enterprise_project_id	String	-	Enterprise project ID. 0: ID of a default project – 1/null: Non-project ID. Non-project indicates that enterprise project management is not available for this cloud service.
enterprise_project_name	String	-	Enterprise project name.
charge_mode	Integer	-	Billing mode. The options are as follows: 1: Yearly/monthly 3: Pay-per-use 10: Reserved instances 11: savings plan
consume_amount	BigDecimal	-	Consumption amount of a cloud service, including the amount of cash coupons and that of flexi-purchase coupons, accurate to eight decimal places. NOTE: The value of consume_amount is equal to the sum of the values of cash_amount, credit_amount, coupon_amount, flexipurchase_coupon_amount, stored_card_amount, bonus_amount, debt_amount, and adjustment_amount.
cash_amount	BigDecimal	-	Amount paid in cash.
credit_amount	BigDecimal	-	Amount paid using the credit.
coupon_amount	BigDecimal	-	Amount paid using the cash coupon.
flexipurchase_coupon_amount	BigDecimal	-	Amount paid using the flexi-purchase coupon.
stored_card_amount	BigDecimal	-	Amount paid using the values-stored card.
bonus_amount	BigDecimal	-	Bonus payment amount (used for the bonus that is not cleared on the live network).
debt_amount	BigDecimal	-	Monthly-paid user: monthly settlement (For details about monthly settlement, click here.) Non-monthly-paid subscriber: outstanding amount
adjustment_amount	BigDecimal	-	Adjustment amount.
official_amount	BigDecimal	-	Standard price.
discount_amount	BigDecimal	-	Discount amount (based on the standard price).
measure_id	Integer	-	Unit. 1: Yuan/Dollar
period_type	Integer	-	Period type. The value can be: 19: Year 20: Month 24: Day 25: Hour 5: One-off
trade_id	String	-	Order ID or transaction ID. If the value of bill_type is 1, 2, 3, 4, or 8, this field indicates the order ID. In other scenarios, it indicates the transaction ID (this parameter represents bills when fees are deducted at the end of a month. Otherwise, this parameter represents receivables.)
id	String	64	Unique ID. This parameter is reserved.
product_spec_desc	String	-	Product specification description.
sub_service_type_code	String	64	Service type code of a child service that is attached to an ECS.
sub_service_type_name	String	200	Service type of a child service that is attached to an ECS.
sub_resource_type_code	String	64	Resource type code of a child resource that is attached to an ECS.
sub_resource_type_name	String	200	Resource type name of a child resource that is attached to an ECS.
sub_resource_id	String	64	Resource ID of a child resource that is attached to an ECS. If the resource is a reserved instance, this parameter indicates a reserved instance ID.
sub_resource_name	String	256	Resource name of a child resource that is attached to an ECS. If the resource is a reserved instance, this parameter indicates a reserved instance name.
pre_order_id	String	64	Original order ID
az_code_infos	List<AzCodeInfo>	-	AZ information list For details, see Table 2.

**Table 2** AzCodeInfo
Parameter	Type	Maximum Length	Description
az_code	String	64	AZ code

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: length
Date: response time  
{
	"monthly_records": [{
		"cycle": "2022-05",
		"bill_date": null,
		"bill_type": 4,
		"customer_id": "05f2******00d50d0f2bc002c46e3020",
		"region": "ap-southeast-1",
                     "region_name": "CN-Hong Kong",
		"cloud_service_type": "hws.service.type.ebs",
		"resource_Type_code": "hws.resource.type.volume",
               "cloud_service_type_name": "Elastic Volume Service",
               "resource_type_name": "Elastic Volume Service",
		"res_instance_id": "220523_dbc6ee4a02964e04adaa0e01b7a1e8e4",
		"resource_name": "hws.resource.type.volumename",
		"resource_tag": null,
		"sku_code": "SATA",
		"enterprise_project_id": null,
               "enterprise_project_name": "Non-project"
		"charge_mode": 1,
		"consume_amount": 0.0,
		"cash_amount": 0.0,
		"credit_amount": 0.0,
		"coupon_amount": 0.0,
		"flexipurchase_coupon_amount": 0.0,
		"stored_card_amount": 0.0,
		"bonus_amount": 0.0,
		"debt_amount": 0.0,
		"adjustment_amount": null,
		"official_amount": 0.0,
		"discount_amount": 0,
		"id": "037e8a2b******01-5f9eb5153cba_1",
		"measure_id": 1,
                "sub_service_type_code": null,
                "sub_service_type_name": null,
                "sub_resource_type_code": null,
                "sub_resource_type_name": null,
                "sub_resource_id": null,
                "sub_resource_name": null,
		"period_type": 20,
		"root_resource_id": null,
		"parent_resource_id": null,
		"trade_id": "CSYD******214V3CC02",
		"product_spec_desc": "Common I/O|200GB",
                "pre_order_id": "CS23******54B1AEW4J",
		"az_code_infos": [{
			"az_code": "cn-north-1c"
		}]
	}],
	"total_count": 7,
	"currency": "USD"
}

Status Code

4xx: This class of HTTP status code is intended for situations in which the error seems to have been caused by the client, for example, the request contains bad syntax or incorrect parameters. You must ensure the request is correct.
5xx: This class of HTTP status code is intended for cases in which the Huawei Cloud server is aware that it has encountered an error or is otherwise incapable of performing the request. In this case, contact Huawei Cloud customer service.