Viewing Resource Usage Details_Customer Operation Capabilities

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.

NOTE:

After a customer associates with an enterprise master in the unified accounting model, bill queries will return both bills before and after the association.
You can query data from the past three years.

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

**Table 1** Header parameters
Parameter	Mandatory	Maximum Length	Description
X-Language	No	10	Language. zh_CN: Chinese en_US: English The default value is en_US.

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
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: The service does not support enterprise project management. 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 to a 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, if there are 10 records that meet query conditions, when you set limit to 10 and offset to 1, the second to the tenth records are returned. If there are 20 records that meet query conditions, when you set offset to 0 and limit to 10 for the first page and set offset to 10 and limit to 10 for the second page, then each page will respectively have 10 records.
limit	No	Integer	1–1000	Page limit. The default value is 10.
statistic_type	No	Integer	1–3	Statistics type. The default value is 1. 1: By billing cycle 2: By day 3: By details 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 billing cycle. DAILY: By day The information type, DAILY, is returned only when the statistic_type is set to 2 or 3. 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 value must be consistent 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 and the value must be consistent with the billing cycle.
payer_account_id	No	String	1–64	The account ID of the payer. If this parameter is not included or is set to null, it will not be used as a filter criterion. It cannot be set to "". NOTE: Independent accounting members of an enterprise and other common customers can only query their own expenditures. For an enterprise master, if this parameter is not included, expenditures of the master, their unified accounting members, and their independent account members are returned; if this parameter is set to the ID of the master, expenditures of the master and their unified accounting members are returned; and if this parameter is set to the ID of an independent accounting member, expenditures of this member are returned. For a unified accounting member of an enterprise, if this parameter is set to the ID of the member, expenditures of the member generated before they were associated with their enterprise master are returned; if this parameter is set to their enterprise master, expenditures of the member generated after they were associated with their enterprise master are returned; and if this parameter is not included, all expenditures are returned.

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
X-Language:en_US
{
      "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 2.
total_count	Integer	-	Number of result sets. This parameter is returned only when the query is successful.
currency	String	3	Currency. USD

**Table 2** 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	8,192	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 null: The service does not support enterprise project management.
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: USD
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, 103, 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	256	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 3.
payer_account_id	String	64	The account ID of the payer. NOTE: If the current account is an individual account, an account of an independent accounting member, or an enterprise master account, this parameter needs to be set to the ID of the current account. For a unified accounting member of an enterprise, this parameter can be set to the ID of the unified accounting member or the ID of their enterprise master.
effective_time	String	32	Start time of using the resource corresponding to the fee. This field is valid when statistic_type is set to 3. This field is reserved when statistic_type is set to 1 or 2.
expire_time	String	32	End time of using the resource corresponding to the fee. This field is valid when statistic_type is set to 3. This field is reserved when statistic_type is set to 1 or 2.
consume_time	String	32	Expenditure time Format: yyyy-MM-dd'T'HH:mm:ss'Z' (UTC time is used.) For yearly/monthly resources, the value of this parameter is same as the bill transaction time. For pay-per-use resources or resources paid by installment, the value of this parameter is the billing start time and end time. NOTE: The value of this parameter is available only when statistic_type is set to 3.
be_id	String	64	Huawei Cloud business entity ID. NOTE: During resource consumption, for a common customer, the value of be_id is 0. For a customer associated with a partner, the value of be_id is not 0. For an enterprise member account that is associated with an enterprise master account for unified accounting, the value of be_id is the same as that of the associated master account.
extend_params	ResRelation Object	-	Resource relationship information. This parameter is reserved. For details, see Table 4.

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

**Table 4** ResRelation
Parameter	Type	Maximum Length	Description
self_resource_id	String	A maximum of 64 characters	ID of the resource corresponding to the current fee.
relation_infos	List<RelationInfo>	-	Resource information associated with the resource ID corresponding to the current fee. For details, see Table 5.

**Table 5** RelationInfo
Parameter	Type	Maximum Length	Description
relative_resource_id	String	A maximum of 128 characters	Associated resource ID.
relative_type	String	-	Associated resource type. PARENT: parent resource ROOT: root resource

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"
		}],
                "payer_account_id": "ZS78******56A1BEF4J",
                "effective_time": "2024-07-06T16:00:00Z",
                "expire_time": "2024-08-06T16:00:00Z",
                "consume_time":null,
                "be_id": "15",
                "extend_params": {
                    "self_resource_id": "BOBOzhengji012101",
                    "relation_infos": [
                        {
                            "relative_resource_id": "BOBOzhengji012101",
                            "relative_type": "ROOT"
                        }
                    ]
              }
         }
    ],
	"total_count": 7,
	"currency": "USD"
}

Status Code

NOTE:

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.

HTTP Value	Error Code	Description
400	CBC.0100	Parameter error.
403	CBC.0151	Access denied.
500	CBC.0999	Unknown error occurred.

Viewing Resource Usage Details