使用 REST API 查看订阅计费

成本管理 API 可帮助你查看和管理 Azure 成本。

特别是成本详细信息 API，通过提供详细、未聚合的成本和使用情况数据来帮助查看和管理 Azure 成本。

使用此异步 API，可以生成和下载订阅的成本报告。

本文介绍如何使用成本详细信息 API 返回给定日期范围的订阅计费详细信息。

小窍门

此 REST API 非常适合自动化方案，需要定期以编程方式检索成本数据。可以将它集成到脚本、应用程序或自动化工作流中，以拉取成本报表进行分析、预算或合规性报告。

重要

成本详细信息 API 是异步的和基于报表的。提交请求以生成可下载的报告文件，查询其完成情况，然后从安全 URL 下载生成的文件。

成本详细信息 API 的工作原理

成本详细信息 API 使用异步工作流：

创建报表：提交 POST 请求以生成订阅的成本详细信息报表
轮询状态：检查操作状态，直至报告完成
下载报表：使用提供的下载 URL 获取包含成本数据的 CSV 文件

注释

API 支持 ActualCost 和 AmortizedCost 指标。 ActualCost 在如原样计费时显示费用，而 AmortizedCost 将预留和节省计划的购买成本在其使用期限内平均分摊，并将成本重新分配给使用预留或节省计划的资源。例如，1 年期保留费用为 365 美元，在购买日期显示为单笔费用。在 AmortizedCost 中，相同的 365 美元作为每日 1.00 美元的使用费分散在受益于预留的使用情况中。

步骤 1：创建报表

提交 POST 请求以启动订阅范围的报表生成：

POST https://management.chinacloudapi.cn/subscriptions/{subscriptionID}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2025-03-01
Content-Type: application/json
Authorization: Bearer {access-token}

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2025-07-01",
    "end": "2025-07-15"
  }
}

步骤 2：轮询报告状态

初始请求返回标头 Location 。使用此 URL 检查报表状态：

GET https://management.chinacloudapi.cn/subscriptions/{subscriptionID}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2025-03-01
Authorization: Bearer {access-token}

步骤 3：下载报表

当响应为“200 - 成功”或状态字段为“完成”时，响应中包含用于下载 CSV 文件的链接 blobLink。

请求参数

{subscriptionID} 参数是必需的，用于标识目标订阅。

请求正文支持以下参数：

metric - 请求的报表类型。可以是 ActualCost 或者 AmortizedCost。如果未指定，则默认为 ActualCost.
timePeriod - 数据请求的日期范围。以 YYYY-MM-DD 格式指定 start 和 end 日期。不能与 invoiceId 或 billingPeriod 参数一起使用。
invoiceId - 所请求的数据发票。微软客户协议的客户在计费档案或客户范围内支持此参数。不能与 billingPeriod 或 timePeriod 参数一起使用。
billingPeriod - 请求的数据计费周期。企业协议客户支持此参数。使用 YearMonth 格式（例如，202408）。不能与 invoiceId 或 timePeriod 参数一起使用。

注释

如果在请求正文中未提供 timePeriod、invoiceId 或 billingPeriod 参数，API 将返回当前月份的成本。

以下标头是必需的：

请求标头	说明
Content-Type：	必需。设置为 `application/json`。
Authorization：	必需。设置为有效的`Bearer`访问令牌。

响应

初始响应（HTTP 202 已接受）

初始 POST 请求返回状态代码 202（已接受），其中包含响应标头：

Name	类型	说明
位置	String	用于检查异步操作状态的 URL
Retry-After	整数	要生成的报表的预期时间（以秒为单位）

轮询响应（HTTP 200 正常）

报告完成后，轮询终结点返回状态代码 200（确定），其中包含报告详细信息：

{
  "id": "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.CostManagement/operationResults/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "name": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2025-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2025-07-01",
          "end": "2025-07-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2025-07-28T08:08:46.1973252Z"
}

关键响应字段

响应属性	说明
地位	报告生成的状态（InProgress、Completed、Failed）
dataFormat	生成的报表的格式（CSV）
blobCount	报告数据集中的 Blob 文件数量
byteCount	报表数据集的总大小（以字节为单位）
blobLink	下载成本详细信息 CSV 文件的 URL
validTill	下载 URL 的到期日期/时间

成本明细文件字段

下载的 CSV 文件包含以下关键字段的详细成本和使用情况数据：

领域	说明
日期	费用的使用情况或购买日期
SubscriptionId	Azure 订阅的唯一标识符
订阅名称	Azure 订阅的名称
ResourceGroup	资源位于的资源组的名称
ResourceName	资源的名称
ResourceId	Azure 资源管理器资源的唯一标识符
MeterCategory	计量的分类类别的名称（例如云服务、网络）
MeterName	计量的名称
数量	产品或服务使用的单位数
UnitOfMeasure	服务的计费单位
CostInBillingCurrency	信用额度或税款之前计费货币的收费成本
BillingCurrency	与计费帐户关联的货币
充电类型	用于表示费用是使用（Usage）、购买（Purchase）还是退款（Refund）
PricingModel	指示计量定价方式的标识符（OnDemand、Reservation、Spot、SavingsPlan）

有关所有字段及其说明的完整列表，请参阅 “了解成本详细信息”字段。

最佳做法

请求频率：针对给定的范围和日期范围每天最多生成一次报告。每四小时刷新一次成本数据。
日期范围：对于大型数据集，限制日期范围（例如生成每日或每周报表），以保持文件大小可管理。
数据保留：立即下载和存储报表。下载 URL 将在短时间内过期（通常为一小时）。

错误处理

其他状态代码指示错误条件。响应对象解释了请求失败的原因：

{
  "error": [
    {
      "code": "Error type.",
      "message": "Error response describing why the operation failed."
    }
  ]
}

后续步骤

Last updated on 2025-09-28

通过