# 查询成本数据-ListCosts #### 功能介绍 客户在自建平台查询成本分析数据。 ![](https://support.huaweicloud.com/api-oce/public_sys-resources/note_3.0-zh-cn.png) - 原始成本：当月的原始成本数据和费用中心账单之间存在1小时左右的时延，最终以实际出账日（次月3日）以后的数据为准，在次月4日12点后可查看。 - 摊销成本：摊销成本为非实时数据，每24小时刷新一次，有24\~48小时左右的延迟。CDN、VPC等按月结算的产品，当月消费需在次月4日12点后查看。 #### 接口约束 该接口只允许使用客户AK/SK或者Token调用。 上个月的数据需在出账后查询。 #### 调试 您可以在[API Explorer](https://apiexplorer.developer.huaweicloud.com/apiexplorer/debug?product=BSS&api=ListCosts)中调试该接口，支持自动认证鉴权。API Explorer可以自动生成SDK代码示例，并提供SDK代码示例调试功能。 #### 授权信息 账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。 - 如果使用角色与策略授权，具体权限要求请参见[策略授权参考](https://support.huaweicloud.com/api-oce/jac_000053.html)。 - 如果使用身份策略授权，需具备如下身份策略权限。 | 授权项 | 描述 | 访问级别 | 资源类型（\*为必须） | 条件键 | 别名 | |:---|:---|:---|:---|:---|:---| | costCenter:costAnalysis:listCosts | 授予查看成本分析的权限 | read | - | - | - | #### URI POST /v4/costs/cost-analysed-bills/query 表1Header参数 | 参数 | 是否必选 | 取值范围 | 描述 | |:---|:---|:---|:---| | X-Language | 否 | 最大长度：8 | 语言，预留字段。 - 中文：zh_CN - 英文：en_US 缺省为zh_CN。 | #### 请求消息 **请求参数** | 参数 | 是否必选 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---|:---| | time_condition | 是 | TimeCondition Object | - | 时间条件，具体请参见[表 TimeCondition]。 | | groupby | 是 | List\ | 最大个数：3 | 查询维度，具体请参见[表3]。 | | cost_type | 是 | String | 最大长度：256 | 成本类型。 - ORIGINAL_COST：原始成本 - AMORTIZED_COST：摊销成本 | | amount_type | 是 | String | - | 展示的金额类型。 - PAYMENT_AMOUNT：应付 - NET_AMOUNT：实付 | | filters | 否 | List\ | 最小长度：0 最大长度：100 | 过滤条件，具体请参见[表4]。 此参数不携带或携带值为空列表或携带值为null时，不作为筛选条件。 | | offset | 否 | Integer | \[0-200000\] | 偏移量，从0开始，默认值为0。 说明： offset用于分页处理，如不涉及分页，请使用默认值0。offset表示相对于满足条件的第一个数据的偏移量。如offset = 1，则返回满足条件的第二个数据至最后一个数据。 例如，满足查询条件的结果共10条数据，limit取值为10，offset取值为1，则返回的数据为2\~10，第一条数据不返回。 | | limit | 否 | Integer | \[1-1000\] | 每次查询的记录数，默认为10。 | 表2TimeCondition | 参数 | 是否必选 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---|:---| | time_measure_id | 是 | Integer | \[1-2\] | 时间单位。 - 1：天 - 2：月 | | begin_time | 是 | String | 32 | 查询开始时间，东八区时间，必须为日期格式。 - 当time_measure_id值为1时，格式为YYYY-MM-DD - 当time_measure_id值为2时，格式为YYYY-MM | | end_time | 是 | String | 32 | 查询结束时间，东八区时间，必须为日期格式。 - 当time_measure_id值为1时，格式为YYYY-MM-DD - 当time_measure_id值为2时，格式为YYYY-MM 须知： 按天或按月查询均只支持查询18个月内的成本数据。 | 表3GroupBy | 参数 | 是否必选 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---|:---| | type | 是 | String | 最大长度：64 | - tag：按照成本标签过滤 - cost_unit：按照成本分组过滤 - dimension：默认取值 | | key | 是 | String | 最大长度：128 | - 如果type为tag，此处取值为tag的key。 - 如果type为cost_unit，此处取值为cost_unit的key。 - 如果type为dimension，此处取值如下： - CLOUD_SERVICE_TYPE：产品类型 - ASSOCIATED_ACCOUNT：关联账号 说明： 如果企业主账号有查看名下企业子账号消费数据的权限，即可查看其成本数据；如果是非企业主账号查看，则只能看到自己的账号。 - REGION_CODE：区域 - RES_SPEC_CODE：规格编码 - USAGE_TYPE：使用量类型 - ENTERPRISE_PROJECT_ID：企业项目 - RESOURCE_ID：资源 - CHARGING_MODE：计费模式 - BILL_TYPE：账单类型 - RESOURCE_TYPE：产品 - AZ_CODE：可用区 - BE_ID：运营实体（beid） - PAYER_ACCOUNT_ID：交易账号 - SPLIT_ITEM_NAME：分拆项 | 表4Filter | 参数 | 是否必选 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---|:---| | operator | 是 | Integer | \[0-1\] | 运算符。 - 0：仅包含 - 1：仅排除 | | filter_factor | 是 | FilterFactor Object | - | 过滤器因子，具体请参见[表 FilterFactor]。 | 表5**FilterFactor** | 参数 | 是否必选 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---|:---| | key | 是 | String | 最大长度：256 | 维度分组条件。 - CLOUD_SERVICE_TYPE：产品类型 - ASSOCIATED_ACCOUNT：关联账号 说明： 此参数填写关联账号的华为云id。 如果企业主账号有查看名下企业子账号消费数据的权限，即可查看其成本数据；如果是非企业主账号查看，则只能看到自己的账号。 - REGION_CODE：区域 - RES_SPEC_CODE：规格编码 - USAGE_TYPE：使用量类型 - ENTERPRISE_PROJECT_ID：企业项目 - RESOURCE_ID：资源 - CHARGING_MODE：计费模式 - BILL_TYPE：账单类型 - RESOURCE_TYPE：产品 - AZ_CODE：可用区 - BE_ID：运营实体（beid） - PAYER_ACCOUNT_ID：交易账号 - RESOURCE_TAG：成本标签 - COST_UNIT：成本分组 - SPLIT_ITEM_NAME：分拆项 说明： 成本类型为"ORIGINAL_COST：原始成本"时，不支持按"SPLIT_ITEM_NAME：分拆项"维度查询。 | | value | 是 | List\ | 最小个数：1 最大个数：100 | 过滤器值。 说明： 当 key 为 CHARGING_MODE时，value 值对应如下： - 包年/包月：1 - 按需：3 - 节省计划：11 当 key 为 BILL_TYPE时，value 值对应如下： - 消费-新购：1 - 消费-续订：2 - 消费-变更：3 - 消费-退订：4 - 消费-使用：5 - 消费-自动续订：8 - 调账-补偿：9 - 预留实例-合并拆分：11 - 消费-退订手续费增收：13 - 消费-服务支持计划月末补扣：14 - 调账-扣费：16 - 消费-按月付费：18 - 退款-变更：20 - 消费-节省计划抵扣：23 - 退款-包年/包月转按需：24 - 消费-抹零补扣：25 - 消费-按年付费：103 - 消费-节省计划未抵扣：200 - 消费-资源包抵扣：201 - 消费-资源包未抵扣：202 | **请求示例** ``` POST https://bss.myhuaweicloud.com/v4/costs/cost-analysed-bills/query HTTP/1.1 Content-Type: application/json X-Auth-Token：MIIPAgYJKoZIhvcNAQcCo...ggg1BBIINPXsidG9rZ { "amount_type": "PAYMENT_AMOUNT", "offset": 0, "cost_type": "ORIGINAL_COST", "limit": 10, "groupby": [{ "type": "dimension", "key": "CLOUD_SERVICE_TYPE" }], "filters": [{ "filter_factor": { "value": ["cn-north-1"], "key": "REGION_CODE", }, "operator": 0 }], "time_condition": { "end_time": "2021-07-15", "begin_time": "2021-07-14", "time_measure_id": 1 } } ``` #### 响应消息 **响应参数** | 参数 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---| | error_code | String | 最大长度：20 | 状态码。具体请参考[状态码]。只有失败才返回该字段。 | | error_msg | String | 最大长度：1000 | 错误描述信息。只有失败才返回该字段。 | | currency | String | 最大长度：8 | 货币。 - CNY：人民币 | | total_count | Integer | - | 总条数。 | | cost_data | List\ | - | 按天或按月的明细金额，具体请参见[表 CostDataByDimension]。 | 表6CostDataByDimension | 参数 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---| | dimensions | List\ | 最大个数：1 | 维度列表，具体请参见[表 DimensionGroup]。 | | costs | List\ | 最大个数：10000 | 成本值，具体请参见[表 Cost]。 | | amount_by_costs | String | 最大长度：64 | 此维度值对应整个时间跨度的成本汇总金额。 | | official_amount_by_costs | String | 最大长度：64 | 此维度值对应整个时间跨度的官网价汇总金额。 | 表7DimensionGroup | 参数 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---| | key | String | 最大长度：128 | 分组条件。 - 产品类型：CLOUD_SERVICE_TYPE - 企业项目：ENTERPRISE_PROJECT_ID - 使用量类型：USAGE_TYPE - 产品：RESOURCE_TYPE - 可用区：AZ_CODE - 账单类型：BILL_TYPE - 关联账号：ASSOCIATED_ACCOUNT - 规格编码：RES_SPEC_CODE - 运营实体：BE_ID - 区域：REGION_CODE - 计费模式：CHARGING_MODE - 交易账号：PAYER_ACCOUNT_ID - 资源tag：RESOURCE_TAG - 资源id：RESOURCE_ID - 成本分组：COST_UNIT - 分拆项：SPLIT_ITEM_NAME | | value | String | - | 维度值。 说明： 当 key 为 CHARGING_MODE时，value 值对应如下： - 包年/包月：1 - 按需：3 - 节省计划：11 当 key 为 BILL_TYPE时，value 值对应如下： - 消费-新购：1 - 消费-续订：2 - 消费-变更：3 - 消费-退订：4 - 消费-使用：5 - 消费-自动续订：8 - 调账-补偿：9 - 预留实例-合并拆分：11 - 消费-退订手续费增收：13 - 消费-服务支持计划月末补扣：14 - 调账-扣费：16 - 消费-按月付费：18 - 退款-变更：20 - 消费-节省计划抵扣：23 - 退款-包年/包月转按需：24 - 消费-抹零补扣：25 - 消费-按年付费：103 - 消费-节省计划未抵扣：200 - 消费-资源包抵扣：201 - 消费-资源包未抵扣：202 | 表8Cost | 参数 | 参数类型 | 取值范围 | 描述 | |:---|:---|:---|:---| | time_dimension_value | String | 最大长度：20 | 时间维度值。 - 如按天维度，该值为yyyy-mm-dd - 如按月维度，该值为yyyy-mm | | time_measure_id | Int | - | 时间单位。 - 1：天 - 2：月 | | amount | String | 最大长度：64 | 应付或实付的成本金额或均摊金额，具体取决于请求参数。 | | official_amount | String | 最大长度：64 | 官网价金额。 | **响应示例** ``` HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: length Date: response time { "currency": "CNY", "total_count": 1, "cost_data": [ { "dimensions": [ { "key": "tag", "value": "Group:noTagKey" } ], "costs": [ { "time_dimension_value": "2021-08", "time_measure_id": 2, "amount": "13225.00", "official_amount": "13225.00" } ], "amount_by_costs": "13225.00", "official_amount_by_costs": "13225.00" } ] } ``` #### 状态码 ![](https://support.huaweicloud.com/api-oce/public_sys-resources/note_3.0-zh-cn.png) - 状态码4xx：由于明显的客户端错误（例如，格式错误的请求语法、参数错误等），华为云会返回4xx错误码，请及时检查请求消息的正确性，重新发起请求。 - 状态码5xx：由于华为云系统原因，导致无法完成明显有效请求的处理，可及时联系华为云客服处理。 | HTTP状态码 | 错误码 | 错误描述 | |:---|:---|:---| | 400 | CBC.0100 | 参数错误。 | | 400 | CBC.18000014 | 未开通成本中心。 | | 400 | CBC.18000016 | 权限不足，请联系您的合作伙伴。 | | 400 | CBC.18000053 | 权限不足，请联系您的企业主。 | | 500 | CBC.0999 | 其他错误。 | | 400 | CBC.18000048 | 您名下的财务独立子，超过系统可支持查询的数量，请指定企业子账号查询。 |