【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载导读本文围绕 autoskills 仓库中 azure-cost 技能包azure-cost的 Forecast API 请求体 Schemarequest-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-version2023-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 中的字段表字段类型必填可选值说明typestring✅ActualCost、AmortizedCost、Usage预测所使用的成本类型timeframestring✅Customforecast 请求必须为CustomtimePeriodobject✅—预测窗口的起止日期timePeriod.fromstring✅ISO 8601 datetime开始日期可设为过去时间以包含实际成本timePeriod.tostring✅ISO 8601 datetime结束日期必须晚于当前时间才能进行预测datasetobject✅—预测的数据集配置dataset.granularitystring✅Daily、Monthly预测结果的粒度dataset.aggregationobject✅—要应用的聚合函数dataset.aggregation.totalCost.namestring✅Cost要聚合的列名dataset.aggregation.totalCost.functionstring✅Sum聚合函数dataset.sortingarray可选—结果排序方式dataset.sorting[].directionstring可选Ascending、Descending排序方向dataset.sorting[].namestring可选UsageDate排序所依据的列dataset.filterobject可选—过滤表达式dimensions / tagsincludeActualCostboolean可选true、false是否在预测旁附带历史实际成本。默认trueincludeFreshPartialCostboolean可选true、false是否包含最近几天的部分成本数据。默认true要求includeActualCosttrue3.1 必填字段的细节说明typeActualCost是最常用的预测类型对应真实账单成本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时响应会包含最近几天尚未完全结算的部分成本数据账单数据仍在陆续到达的窗口期。⚠️依赖约束该字段要求includeActualCosttrue。如果仅设置includeFreshPartialCosttrue而未设置includeActualCosttrue会触发校验错误DontContainIncludeActualCostWhileIncludeFreshPartialCost错误码详见 error-handling.md。安全做法是始终将两个字段同时显式声明。补充边界按 guardrails.md 的说明includeFreshPartialCost的账单数据晚到容差为 2 天而Monthly 粒度 includeActualCosttrue组合要求显式提供合法的timePeriod含有效的from/to省略时会触发DontContainsValidTimeRangeWhileMonthlyAndIncludeCost错误。五、响应结构解读5.1 响应列Response Columns列类型说明CostNumber成本金额实际或预测UsageDate/BillingMonthDatetime成本行对应的日期CostStatusString标识该行是历史数据还是预测数据CurrencyString货币代码如USD、EUR5.2CostStatus取值含义值含义Actual历史实际成本已产生Forecast预测的未来成本模型预测结果注意CostStatus是 forecast 响应特有的列Query API 的响应中没有该列详见下文对比表。它是区分已花掉的钱与将要花的钱的唯一依据。5.3 粒度与日期列映射粒度日期列DailyUsageDateMonthlyBillingMonth即日粒度预测返回UsageDate列月粒度预测返回BillingMonth列。在构造dataset.sorting时也应按此选择对应的排序列名日粒度用UsageDate月粒度用BillingMonth。六、与 Query API 请求体的关键差异理解 forecast 请求体之前先明确它和兄弟文档 cost-query/request-body-schema.md 的差异有助于避免把 Query API 的习惯误用到 forecast 上方面Forecast APIQuery APIGrouping分组❌ 不支持✅ 通过grouping字段支持最多 2 个维度timeframe通常仅Custom支持Custom、MonthToDate、BillingMonthToDate等多种预设includeActualCost✅ forecast 专属字段❌ 不适用includeFreshPartialCost✅ forecast 专属字段❌ 不适用响应CostStatus列✅ 区分Actual与Forecast行❌ 不存在to日期必须晚于当前时间可为任意合法的过去 / 当前日期两组差异中最值得警惕的是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固定为Customfrom可设为过去如月初以纳入实际成本to必须是未来日期。注意约束最少需要28 天历史成本数据作为训练样本最大预测窗口为10 年详见 guardrails.md。Step 4配置 dataset—— 推荐Daily或Monthly粒度聚合用SumCost不要加入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 }执行命令PowerShellNew-Item -ItemType Directory -Path temp -Force az rest --method post --url /subscriptions/subscription-id/providers/Microsoft.CostManagement/forecast?api-version2023-11-01 --headers ClientTypeGitHubCopilotForAzure --body temp/cost-forecast.json依据 SKILL.md 的最佳实践所有 Cost Management API 请求都应携带ClientType: GitHubCopilotForAzure请求头az rest中为--headers ClientTypeGitHubCopilotForAzure并且优先使用 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 路径而非请求体本身ScopeURL 路径模式订阅/subscriptions/subscription-id/providers/Microsoft.CostManagement/forecast资源组/subscriptions/subscription-id/resourceGroups/rg-name/providers/Microsoft.CostManagement/forecast账单账户/providers/Microsoft.Billing/billingAccounts/id/providers/Microsoft.CostManagement/forecast构造完整请求 URL 时需追加?api-version2023-11-01。账单账户级预测推荐使用月粒度原因见下节的行数上限。九、请求体相关 Guardrails 与错误处理速查9.1 时间与数据约束规则约束to日期必须晚于当前时间numberOfDaysToForecast必须 0from日期可早于当前时间用于纳入实际成本最小训练数据28 天4 周历史成本数据新订阅不足 28 天将无法预测最大预测窗口10 年响应行数上限每响应最多 40 行日粒度 30 天实际 30 天预测会超限建议日粒度只预测 2–3 周更长周期改用月粒度includeFreshPartialCost依赖includeActualCosttrueMonthly includeActualCost要求显式timePeriod其中响应行数上限 40 行是 forecast 特有的约束guardrails.md它直接决定了日粒度预测的时间窗口不宜超过约 2–3 周超过时要么拆分多个小时间窗请求要么切换为月粒度。9.2 常见错误与校验错误码状态码错误场景修复方式400CantForecastOnThePast起止日期都在过去确保to在未来400DontContainsDataSet缺少dataset补齐granularity与aggregation400DontContainIncludeActualCostWhileIncludeFreshPartialCost字段依赖非法设置includeActualCosttrue或将includeFreshPartialCost置为false403权限不足在目标 Scope 上授予Cost Management Reader角色424训练数据不足预测模型无法计算若includeActualCosttrue则回退返回实际成本否则改用 cost-query/workflow.md429触发限流读取所有x-ms-ratelimit-microsoft.costmanagement-*-retry-after响应头qpu、entity、tenant等待最长的重试时长最多重试 3 次完整的错误码参考表含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 请求体的核心要点可以归纳为四条窗口必须指向未来timeframe固定Customto日期必须晚于当前时间否则触发CantForecastOnThePast。dataset 只做聚合、不做分组granularityaggregationSum的Cost是必填核心sorting与filter可选但不能使用grouping。两个布尔开关成对使用includeActualCost与includeFreshPartialCost默认均为true后者强依赖前者务必同时显式声明避免校验错误。用CostStatus解读响应Actual行表示历史实际成本Forecast行表示模型预测配合UsageDate/BillingMonth的粒度映射即可还原完整的成本趋势。如果你需要更完整的调用流程、更多示例模板或更细的限流 / 错误处理策略可直接继续阅读同技能包下的 workflow.md、examples.md、guardrails.md 与 error-handling.md。赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐autoskills 实战Azure Cost Management Forecast API 预测请求示例与 Scope URL 完整指南autoskills 实战Azure Cost Management Forecast API 预测请求示例与 Scope URL 完整指南 导读 本篇文章基Azure Cost Management Forecast API Guardrails 实战指南时间周期校验、训练数据要求与限流处理Azure Cost Management Forecast API Guardrails 实战指南时间周期校验、训练数据要求与限流处理 本文以 packagAzure Cost Management Forecast API 错误处理完全指南状态码、校验错误与重试策略Azure Cost Management Forecast API 错误处理完全指南状态码、校验错误与重试策略 本篇技术指南聚焦 autoskills 仓库上一篇Fluence Rewards项目时空泡沫数据库微观宇宙中的数据存储下一篇3步搞定Ghost会员变现Stripe支付全流程从0到1实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考