通过

你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

按需获取小型成本数据集

  • 项目

使用成本详细信息 API 可获取与 Azure 账单对应的原始、未聚合的成本数据。 当你的组织需要编程数据检索解决方案时，API 非常有用。 如果要分析 2 GB（200 万行）或更小的成本数据集，请考虑使用 API。 但是，对于持续的数据引入工作负载和下载更大的数据集，则应该使用“导出”。

如果要定期获取大量导出的数据，请参阅使用导出功能定期检索大型成本数据集。

要详细了解成本明细（以前称为“使用情况详细信息”）中的数据，请参阅提取成本详细信息数据。

成本详细信息报告仅适用于具有企业协议或 Microsoft 客户协议的客户。 如果你是 MSDN、即用即付或 Visual Studio 客户，请参阅获取即用即付订阅的成本详细信息。

权限

若要使用成本详细信息 API，需要对受支持的功能和范围拥有只读权限。

注意

成本详细信息 API 不支持对 EA 和 MCA 客户使用管理组。

有关详细信息，请参阅：

成本详细信息 API 最佳做法

Microsoft 建议你在使用成本详细信息 API 时遵循以下最佳做法。

请求计划

如果需要获取最新成本数据，建议每天最多查询一次。 报告每四小时刷新一次。 如果更频繁地调用，则会收到相同的数据。 在为历史发票下载成本数据后，除非明确收到通知，否则费用不会更改。 建议在站点上某个可查询的存储中缓存成本数据，以防止对相同数据的重复调用。

对请求进行分块

将调用拆分为较小的日期范围，以获取可通过网络下载的更易管理的文件。 例如，如果你每月的 Azure 成本文件都很大，建议按天或按周来分块。 如果你有包含大量成本数据的范围（例如计费帐户），请考虑将多个调用置于子范围内，以便获得可以下载的更易于管理的文件。 有关成本管理范围的详细信息，请参阅了解和使用范围。 下载数据后，使用 Excel 使用中的筛选器和数据透视表进一步分析数据。

如果你的数据集每月超过 2 GB（或大约 200 万行），请考虑使用导出作为更具可扩展性的解决方案。

延迟和速率限制

对 API 的按需调用在速度方面会受到限制。 生成成本详细信息文件所需的时间与文件中的数据量直接相关。 要了解你的文件可供下载之前的预期时间量，你可以使用 API 响应中的 retry-after 标头。

支持的数据集时间范围

成本详细信息 API 支持每个报表最多包含一个月的数据集。 历史数据最多可检索当前日期前 13 个月。 如果要为 13 个月的历史数据集播种，我们建议对过去 13 个月的一个月数据集进行 13 次调用。 若要检索 13 个月以前的历史数据，请使用导出 REST API。

成本详细信息 API 请求示例

Microsoft 客户使用以下示例请求来解决常见情况。 请求返回的数据对应于计费系统收到成本的日期。 其中可能包含多张发票的费用。 这是一个异步 API。 因此，你进行初始调用以请求你的报表并在响应标头中接收轮询链接。 从那里，你可以轮询提供的链接，直到报表可供你使用。

使用 API 响应中的 retry-after 标头来指示下一次轮询 API 的时间。 此标头提供了你的报告生成所需的估计最短时间。

要了解有关 API 合同的更多信息，请参阅成本详细信息 API。

实际成本与摊销成本

要控制你希望查看实际成本还是摊销成本报告，请更改初始请求正文中用于度量字段的值。 可用的指标值是 ActualCost 或 AmortizedCost。

摊销成本会将预留购买细分成每日区块，将其平摊到整个预留期间。 例如，你会看到从 1 月 1 日到 12 月 31 日这段时间每天都有一个 1.00 美元的购买项，而不是在 1 月 1 日有一个 365 美元的购买项。 除了基本摊销，系统还会将这些成本重新分配并与使用了预留的特定资源相关联。 例如，如果将 1.00 美元的每日费用分摊到两个虚拟机，则会看到该日有两个 0.50 美元的费用。 如果该日的部分预留未使用，则会看到一个与相应的虚拟机关联的 0.50 美元费用，以及另一个费用类型为 UnusedReservation 的 0.50 美元费用。 未使用的预留成本只能在查看摊销成本时看到。

必须指出，由于成本表示方式发生变化，实际成本和摊销成本视图会显示不同的总计数字。 通常，在查看摊销成本时，预订购买的几个月总成本会随着时间的推移而降低。 预留购买后的月份成本将增加。 摊销仅适用于预留购买，目前不适用于 Azure 市场购买。

创建报表的初始请求

POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2022-05-01

请求正文：

以下是针对指定日期范围的 ActualCost 数据集的示例请求。

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2020-03-01",
    "end": "2020-03-15"
  }
}

用于生成正确 URI 的可用 {scope} 选项记录在标识范围的资源 ID 中。

以下是可以在报告请求正文中提供的可用字段。

  • metric - 请求的报表类型。 它可以是 ActualCost 或 AmortizedCost。 不需要。 如果未指定该字段，API 将默认为 ActualCost 报告。
  • timePeriod - 为你的数据请求的日期范围。 不需要。 此参数不能与 invoiceId 或 billingPeriod 参数一起使用。 如果请求正文中未提供 timePeriod、invoiceId 或 billingPeriod 参数，API 会返回当月的费用。
  • invoiceId - 为你的数据请求的发票。 此参数仅由 Microsoft 客户协议客户使用。 此外，它只能在计费配置文件或客户范围内使用。 此参数不能与 billingPeriod 或 timePeriod 参数一起使用。 如果请求正文中未提供 timePeriod、invoiceId 或 billingPeriod 参数，API 会返回当月的费用。
  • billingPeriod - 为你的数据请求的计费周期。 此参数仅由企业协议客户使用。 使用 YearMonth 格式。 例如 202008。 此参数不能与 invoiceId 或 timePeriod 参数一起使用。 如果请求正文中未提供 timePeriod、invoiceId 或 billingPeriod 参数，API 会返回当月的费用。

API 响应：

Response Status: 202 – Accepted：指示已接受请求。 使用 Location 标头检查状态。

响应标头：

名称 类型 格式 说明
位置 字符串 检查异步操作结果的 URL。
Retry-After Integer Int32 生成报表的预期时间。 在再次轮询之前等待此持续时间。

报表轮询和下载

请求创建成本详细信息报告后，使用 API 响应的 location 标头中提供的终结点轮询报告。 下面是一个轮询请求示例。

报告轮询请求：

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

Response Status 200 – Succeeded：指示请求成功。

{
  "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": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}

以下是 API 响应中的关键字段摘要：

  • manifestVersion - 响应中使用的清单合同的版本。 此时，对于给定的 API 版本，清单版本将保持不变。
  • dataFormat - CSV 是目前 API 提供的唯一支持的文件格式。
  • blobCount - 表示报表数据集中存在的单个数据 blob 的数量。 请务必注意，此 API 可能会在响应中提供包含多个文件的分区数据集。 设计你的数据管道以能够相应地处理分区文件。 借助分区，可更快地引入更大的数据集。
  • byteCount - 报表数据集在所有分区中的总字节数。
  • compressData - 第一个版本的压缩总是设置为 false。 不过，API 将来会支持压缩。
  • requestContext - 为报告请求的初始配置。
  • blobs - 一起构成完整报告的 n 个 blob 文件的列表。
    • blobLink - 单个 blob 分区的下载 URL。
    • byteCount - 单个 blob 分区的字节数。
  • validTill - 报表不再可访问的日期。

相关内容