Azure Cost Management Forecast API 请求体 Schema 完全指南：从字段解析到实战调用

导读

本文围绕 autoskills 仓库中 azure-cost 技能包（azure-cost）的 Forecast API 请求体 Schema（request-body-schema.md）展开，系统讲解 Azure Cost Management Forecast API 的完整 JSON 请求结构、全部字段含义与取值范围、forecast 专属选项的行为约束，以及响应结构如何区分实际成本与预测成本。读完本文，你将能够独立构造一份可运行的 forecast 请求体，通过az rest调用该 API 完成未来成本预测，并理解它与历史成本 Query API 的关键差异与适用边界。

一、Forecast API 与请求体总体结构

Azure Cost Management Forecast API 用于在指定时间窗口内预测未来的云成本。在 autoskills 的 azure-cost 技能中，其调用入口固定为：

POST {scope}/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01

其中{scope}可以是订阅、资源组、管理组、账单账户或账单配置文件（完整的 Scope 对照表见 SKILL.md）。请求体整体分为三块：顶层字段（type/timeframe/timePeriod/includeActualCost/includeFreshPartialCost）、dataset 数据集配置（granularity/aggregation/sorting/filter），以及 forecast 特有的布尔开关。下面先给出完整 JSON 示例，再逐字段解析。

二、完整 JSON Schema 示例

以下是一份可直接参考的完整 forecast 请求体（来自 request-body-schema.md）：

{ "type": "ActualCost", "timeframe": "Custom", "timePeriod": { "from": "2024-01-01T00:00:00Z", "to": "2024-03-31T00:00:00Z" }, "dataset": { "granularity": "Daily", "aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }, "sorting": [ { "direction": "Ascending", "name": "UsageDate" } ], "filter": { "dimensions": { "name": "ResourceGroupName", "operator": "In", "values": ["my-resource-group"] } } }, "includeActualCost": true, "includeFreshPartialCost": true }

这份请求的语义是：在2024-01-01至2024-03-31的窗口内，以日粒度汇总Cost列的Sum，按UsageDate升序排列，仅保留资源组my-resource-group的成本记录，同时返回历史实际成本与近期未结算的零散成本数据。

三、字段参考表（Field Reference）

下表完整列出请求体各字段的类型、是否必填、可选值与说明，直接对应 request-body-schema.md 中的字段表：

3.1 必填字段的细节说明

• type：ActualCost是最常用的预测类型，对应真实账单成本；AmortizedCost用于预留实例 / 节省计划成本的预测；Usage表示用量型成本数据（可对照 cost-query/workflow.md 中的报告类型说明）。
• timeframe：与 Query API 支持多种预设时间窗不同，forecast 请求必须显式指定Custom，并通过timePeriod提供起止日期。from可以落在过去（此时响应会先返回历史实际成本、再返回未来预测），但to必须指向未来——如果from与to都在过去，API 将返回CantForecastOnThePast错误。
• dataset：必填。缺少dataset会触发校验错误DontContainsDataSet（详见 error-handling.md 的校验错误参考表）。dataset内至少需要granularity与aggregation。

3.2 可选字段的细节说明

• dataset.sorting：用于控制返回行的顺序。按日粒度时通常按UsageDate排序；按月粒度时按BillingMonth排序（参见 examples.md 中的月度示例）。
• dataset.filter：结构上与 Query API 一致，支持dimensions（如ResourceGroupName）与tags两类过滤目标，配合In、Equal、Contains等比较运算符使用。注意 forecast 的过滤常用于在订阅级范围上"圈定"某个资源组或标签，从而预测局部成本。

四、Forecast 专属字段详解

includeActualCost与includeFreshPartialCost是 forecast 请求体区别于 Query API 的两个核心布尔开关，也是理解响应语义的关键。

4.1includeActualCost

• 类型：boolean
• 默认值：true
• 当为true时，响应会包含从from日期到当天为止的历史实际成本行（CostStatus为Actual），以及从当天到to日期的预测成本行（CostStatus为Forecast），二者在同一响应中拼接返回。
• 当为false时，响应仅返回预测（projected）行，不含任何历史数据。

4.2includeFreshPartialCost

• 类型：boolean
• 默认值：true
• 当为true时，响应会包含最近几天尚未完全结算的部分成本数据（账单数据仍在陆续到达的窗口期）。
• ⚠️依赖约束：该字段要求includeActualCost=true。如果仅设置includeFreshPartialCost=true而未设置includeActualCost=true，会触发校验错误DontContainIncludeActualCostWhileIncludeFreshPartialCost（错误码详见 error-handling.md）。安全做法是始终将两个字段同时显式声明。

补充边界：按 guardrails.md 的说明，includeFreshPartialCost的"账单数据晚到容差"为 2 天；而Monthly 粒度 +includeActualCost=true组合要求显式提供合法的timePeriod（含有效的from/to），省略时会触发DontContainsValidTimeRangeWhileMonthlyAndIncludeCost错误。

五、响应结构解读

5.1 响应列（Response Columns）

5.2CostStatus取值含义

注意：CostStatus是 forecast 响应特有的列，Query API 的响应中没有该列（详见下文对比表）。它是区分"已花掉的钱"与"将要花的钱"的唯一依据。

5.3 粒度与日期列映射

即：日粒度预测返回UsageDate列，月粒度预测返回BillingMonth列。在构造dataset.sorting时也应按此选择对应的排序列名（日粒度用UsageDate，月粒度用BillingMonth）。

六、与 Query API 请求体的关键差异

理解 forecast 请求体之前，先明确它和兄弟文档 cost-query/request-body-schema.md 的差异，有助于避免把 Query API 的习惯误用到 forecast 上：

两组差异中最值得警惕的是Grouping 硬限制：forecast 请求体不接受grouping字段（这是 Forecast API 的硬性限制，见 guardrails.md 的分组限制章节）。若用户需要按服务 / 资源组分组的预测，应告知其改用 cost-query/workflow.md 获取带分组的历史成本数据。此外，Query API 的aggregation.name还支持PreTaxCost、UsageQuantity等列，而 forecast 请求体中以Cost列 +Sum函数为典型用法。

七、实战：构造请求体并通过az rest执行

将上面的 Schema 与 cost-forecast/workflow.md 的六步流程结合，即可完成一次真实预测：

Step 1：确定 Scope—— 按 SKILL.md 中的 Scope 表选取订阅或资源组路径。

Step 2：选择报告类型—— 预测通常选ActualCost；涉及预留实例 / 节省计划时选AmortizedCost。

Step 3：设置时间窗口——timeframe固定为Custom；from可设为过去（如月初）以纳入实际成本，to必须是未来日期。注意约束：最少需要28 天历史成本数据作为训练样本，最大预测窗口为10 年（详见 guardrails.md）。

Step 4：配置 dataset—— 推荐Daily或Monthly粒度，聚合用Sum+Cost，不要加入grouping。

Step 5：设置 forecast 专属选项—— 按默认值显式声明includeActualCost: true与includeFreshPartialCost: true。

Step 6：构造并执行—— 创建temp/cost-forecast.json：

{ "type": "ActualCost", "timeframe": "Custom", "timePeriod": { "from": "<first-of-month>", "to": "<last-of-month>" }, "dataset": { "granularity": "Daily", "aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }, "sorting": [{ "direction": "Ascending", "name": "UsageDate" }] }, "includeActualCost": true, "includeFreshPartialCost": true }

执行命令（PowerShell）：

New-Item -ItemType Directory -Path "temp" -Force az rest --method post ` --url "/subscriptions/<subscription-id>/providers/Microsoft.CostManagement/forecast?api-version=2023-11-01" ` --headers "ClientType=GitHubCopilotForAzure" ` --body '@temp/cost-forecast.json'

依据 SKILL.md 的最佳实践，所有 Cost Management API 请求都应携带ClientType: GitHubCopilotForAzure请求头（az rest中为--headers "ClientType=GitHubCopilotForAzure"），并且优先使用 REST API 而非az costmanagement子命令。

八、常用场景模板（可直接套用）

以下模板来自 cost-forecast/examples.md，展示了不同粒度与 Scope 下的请求体写法。

8.1 预测本月剩余天数的成本（日粒度）

{ "type": "ActualCost", "timeframe": "Custom", "timePeriod": { "from": "<first-of-month>", "to": "<last-of-month>" }, "dataset": { "granularity": "Daily", "aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }, "sorting": [ { "direction": "Ascending", "name": "UsageDate" } ] }, "includeActualCost": true, "includeFreshPartialCost": true }

提示：from设为月初，响应会返回截至今天的Actual行和剩余天数的Forecast行。

8.2 预测未来 3 个月（月粒度）

{ "type": "ActualCost", "timeframe": "Custom", "timePeriod": { "from": "<first-of-month>", "to": "<3-months-out>" }, "dataset": { "granularity": "Monthly", "aggregation": { "totalCost": { "name": "Cost", "function": "Sum" } }, "sorting": [ { "direction": "Ascending", "name": "BillingMonth" } ] }, "includeActualCost": true, "includeFreshPartialCost": true }

提示：月粒度响应的日期列是BillingMonth，排序字段也需对应修改。

8.3 资源组 / 账单账户级预测

资源组与账单账户的差异体现在URL 的 Scope 路径而非请求体本身：

构造完整请求 URL 时需追加?api-version=2023-11-01。账单账户级预测推荐使用月粒度（原因见下节的行数上限）。

九、请求体相关 Guardrails 与错误处理速查

9.1 时间与数据约束

其中"响应行数上限 40 行"是 forecast 特有的约束（guardrails.md），它直接决定了日粒度预测的时间窗口不宜超过约 2–3 周；超过时要么拆分多个小时间窗请求，要么切换为月粒度。

9.2 常见错误与校验错误码

完整的错误码参考表（含EmptyForecastRequestBody、InvalidForecastRequestBody、DontContainsValidTimeRangeWhileContainsPeriod等）见 error-handling.md。

9.3 一个容易误判的场景

当 API 返回 "Forecast is unavailable for the specified time period" 时，这不是错误，而是一个合法的响应，表示当前 Scope 的历史数据不足（少于 28 天）或从未产生过成本，预测模型无法生成结果。此时不应重试，而应建议用户改用 cost-query/workflow.md 获取已有的历史数据（见 guardrails.md 的 Forecast Availability 章节）。

十、小结

构造 Azure Cost Management Forecast API 请求体的核心要点可以归纳为四条：

1. 窗口必须指向未来：timeframe固定Custom，to日期必须晚于当前时间，否则触发CantForecastOnThePast。
2. dataset 只做聚合、不做分组：granularity+aggregation（Sum的Cost）是必填核心，sorting与filter可选，但不能使用grouping。
3. 两个布尔开关成对使用：includeActualCost与includeFreshPartialCost默认均为true，后者强依赖前者，务必同时显式声明，避免校验错误。
4. 用CostStatus解读响应：Actual行表示历史实际成本，Forecast行表示模型预测，配合UsageDate/BillingMonth的粒度映射即可还原完整的成本趋势。

如果你需要更完整的调用流程、更多示例模板或更细的限流 / 错误处理策略，可直接继续阅读同技能包下的 workflow.md、examples.md、guardrails.md 与 error-handling.md。