按需获取小型成本数据集

项目
03/05/2024

使用成本详细信息 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.chinacloudapi.cn/{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.chinacloudapi.cn/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

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

{
  "id": "subscriptions/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/operationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "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 - 报表不再可访问的日期。

后续步骤

阅读引入成本详细信息数据一文。
详细了解如何选择成本详细信息解决方案。
了解成本详细信息字段。
使用导出在 Azure 门户中创建并管理导出的数据。
使用 API 大规模自动执行导出创建和引入。

Share via