访问 FOCUS 费用和使用报告

FinOps 开放成本和使用规格 (FOCUS) 为技术计费数据集建立了统一要求。MongoDB Atlas 在 FOCUS 1.3 中提供账单费用和使用数据。格式.您可以从 Atlas 控制台的 Invoices 页面或使用 FOCUS 数据 API 生成 FOCUS 报告。

关于 FOCUS

历史上，Atlas 计费数据以 MongoDB 特定格式提供。Atlas 客户（尤其是大型企业和合作伙伴）需要花费人工努力将 Atlas 信用单位 (ACU) 转换为计费货币。

FOCUS 提供了常见词汇和计费结构，可帮助您了解、对账和集成 Atlas 计费数据与 FinOps 和跨供应商费用管理工具。

PDF 和 CSV 使用概要以 MongoDB 特定格式呈现您的发票。FOCUS 费用和使用报告以标准化的 FOCUS 格式呈现相同的计费周期。您可以从 Atlas 控制台中的 Invoices 页面下载所有三个。

FOCUS 数据API功能

FOCUS 数据API提供对 FOCUS 格式的费用和使用量数据的编程访问权限。

借助 FOCUS 数据 API，您可以：

以计费货币查看费用：直接以计费货币访问 BilledCost 和 EffectiveCost，无需手动转换。
识别信用类型：通过 Contract Applied 字段查看信用是预付、促销还是弹性信用。
分析具有完整上下文的费用：使用 Region、UsageDate 和 ServiceCategory 等字段进行粒度费用分析。
使用标准行业术语：使用 SubAccountName 和其他直观的 FOCUS 术语，而不是内部 API 术语，例如 groupName。

FOCUS 列参考

下表列出了 FOCUS 数据 API 响应中返回的列及其相应的旧版计费字段：

关注 1.3列 ID	定义	当前 CSV 等效字段	当前 JSON 等效字段
`BilledCost`	在当前开票周期内收取的计费货币费用。	不适用	不适用
`BillingAccountId`	此发票的 Atlas 组织 ID。	组织 ID	不适用
`BillingAccountName`	此发票的 Atlas 组织名称。	组织名称	不适用
`BillingCurrency`	此费用的计费货币。	不适用	不适用
`BillingPeriodEnd`	计费周期的结束日期。计费周期不包括结束日期。	不适用	"endDate" (发票)
`BillingPeriodStart`	开始开票期间的日期。计费周期包括开始日期。	不适用	“created”（发票）
`ChargeCategory`	根据计费性质对费用进行分类。例如，"使用量" 表示根据消耗的服务或资源数量计费。	不适用	不适用
`ChargeDescription`	有关收费的高级上下文。	说明	不适用
`ChargePeriodEnd`	发生费用的期间结束。计费周期不包括结束日期。	不适用	“endDate”（lineItems）
`ChargePeriodStart`	发生费用的周期开始。计费周期包括开始日期。	使用日期	"startDate" (lineItems)
`ConsumedQuantity`	与所使用的资源或服务相关的给定 SKU 的体积，具体取决于消耗的单位。	数量	"quantity"
`ConsumedUnit`	用于计量给定 SKU 的单位。	单位	"unit"
`ContractApplied`	一组将费用与一个或多个合同承诺关联的属性。标识用于覆盖已消耗使用量的 Atlas 信用名称。	不适用	不适用
`ContractedCost`	表示通过乘以合同单价和对应的定价数量计算得出的费用。此字段以计费货币计价。	不适用	不适用
`ContractedUnitPrice`	相关 SKU 单个定价单位的协定单价，包括折扣。此价格以计费货币计价。	不适用	不适用
`EffectiveCost`	表示在应用所有降低费率和折扣后的费用摊销成本。此字段以计费货币计价。	不适用	不适用
`HostProviderName`	提供服务提供商部署资源和服务的根本的基础设施的实体名称。例如：AWS、Azure、GCP。	不适用	不适用
`InvoiceIssuer`	负责对消耗的资源或服务开具发票的实体。例如，对于直接与 MongoDB 交易的客户，则为 MongoDB；对于通过市场与 Atlas 交易的客户，则为市场。	不适用	不适用
`ListCost`	表示通过将列表单价与对应定价数量相乘计算得出的费用。此字段以计费货币计价。	不适用	不适用
`ListUnitPrice`	相关 SKU 单个定价单位的建议提供商发布单价，不包括任何折扣。此价格以计费货币计价。	不适用	不适用
`PricingCurrency`	此费用的计量货币，示例 Atlas 信用。	不适用	不适用
`PricingCurrencyContractedUnitPrice`	相关 SKU 单个定价单位的协定单价，包括折扣。此价格以定价货币计价。	不适用	不适用
`PricingCurrencyEffectiveCost`	表示在应用所有降低费率和折扣后的收费的摊销成本。此字段以定价货币计价。	金额	"totalPriceCents"
`PricingCurrencyListUnitPrice`	表示通过将列表单价与对应定价数量相乘计算得出的费用。此字段以定价货币计价。	单价	"unitPriceDollars"
`PricingQuantity`	表示与使用或购买的资源或服务相关联的给定 SKU 的使用量，基于定价单位。	不适用	不适用
`PricingUnit`	表示用于确定单价的单位，示例 GB-小时。	不适用	不适用
`RegionId`	用于孤立的地理区域的标识符，在该区域中预配资源或提供服务。例如：`us-east-1`。	不适用	不适用
`RegionName`	资源预配或服务提供的孤立地理区域的名称。示例，`N. Virginia`。	区域	不适用
`ResourceName`	对于 Atlas，这是集群名称。	集群	"clusterName"
`ServiceCategory`	由 FOCUS 定义的最高级别分类。这是 MongoDB Atlas 的“数据库”。	不适用	不适用
`ServiceName`	代表可以从服务提供商（例如 MongoDB Atlas）购买的产品。	不适用	不适用
`ServiceProviderName`	提供可用于使用或购买的资源或服务的实体名称。例如，MongoDB。	不适用	不适用
`SkuId`	库存单位 (SKU)的唯一标识符，代表一个独立的可计费配置。	不适用	不适用
`SkuMeter`	相关 SKU 的测量单位，表示正在测量的内容，例如 `GB`、计算时间或请求。	不适用	不适用
`SkuPriceDetails`	计费时的价格点的价格维度，以 JSON 中的键值对形式存储。当计费没有价格点或价格点未指定维度时，此列为空。	不适用	不适用
`SkuPriceId`	计费所在价格点的唯一标识符。	不适用	不适用
`SubAccountId`	分帐户的标识符，分帐户是基于组织构建的分组。这相当于 MongoDB Atlas 中的项目。	项目 ID	"groupId"
`SubAccountName`	子帐户的显示名称。这相当于 MongoDB Atlas 中的项目。	项目	"groupName"
`Tags`	分配给相关资源的标签。	标签/应用程序	"tags"
`x_AtlasSku`	正在计费的 Atlas SKU。	SKU	"sku"
`x_BilledDateEnd`	MongoDB 开始对该费用开具的时间段结束。	Date	"created" (lineItems)
`x_BilledDateStart`	MongoDB 开始对该费用开具的时间段。	不适用	不适用
`x_PricingCurrencyRate`	Atlas 信用的“价格”。应用此费率可查找计费货币中 Atlas 信用的费用。	不适用	不适用
`x_SkuCategory`	用于相关 Atlas SKU 的最高级别分类。例如：`Clusters`或`Backup`。	不适用	不适用

端点

FOCUS 数据 API 通过三个终结点扩展 Atlas Administration API：

列出组织的发票列出组织的可用发票。
请求 FOCUS 报告请求生成 FOCUS 格式的计费报告。
检索 FOCUS 报告返回该报告的状态，当报告就绪后，返回下载该报告的 URL。

注意

所有终结点都需要 Organization Billing Admin、Organization Owner 或 Organization Billing Viewer 角色。

列出组织的发票

检索可用发票 ID 列表。对于跨组织计费，此终结点用于标识所有链接组织的发票。

基本 URL： /api/atlas/v2/orgs/{orgId}/associatedInvoices

GET /api/atlas/v2/orgs/{orgId}/associatedInvoices

请求路径参数

名称	类型	必要性	说明
`orgId`	字符串	必需	标识组织的唯一 24 位十六进制数字字符串。

请求查询参数

以下查询参数为可选参数：

名称	类型	必要性	说明	默认
`month`	整型	Optional	要检索的发票月份 (1-12)。	当前月
`year`	整型	Optional	要检索的发票年份。必须 >= 2000。	当前年份
`includeLinkedOrgs`	布尔	Optional	标志，指示是否包含来自链接组织的发票。	`false`

请求示例

curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --request GET "https://cloud.mongodb.com/api/atlas/v2/orgs/{orgId}/associatedInvoices"

响应

{
  "associatedInvoices": [
    {
      "invoiceId": "string",
      "orgId": "string"
    }
  ],
  "month": "06",
  "year": "2026"
}

响应元素

名称	类型	说明
`associatedInvoices`	阵列	指定期间与组织相关的发票列表。
`associatedInvoices[n].invoiceId`	字符串	用于标识发票的唯一 24 位十六进制数字标识符。
`associatedInvoices[n].orgId`	字符串	组织的唯一 24十六进制数字标识符。
`month`	字符串	两位数字，表示相关发票的月份，例如 `06`。
`year`	字符串	表示相关发票年份的四位数，示例为 `2026`。

请求 FOCUS 报告

请求以 FOCUS 标准格式生成账单。Atlas 会异步生成报告，并返回报告 ID，您可以使用该 ID 查询报告状态。

基本 URL： /api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports

POST /api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports

请求路径参数

名称	类型	必要性	说明
`orgId`	字符串	必需	标识组织的唯一 24 位十六进制数字字符串。
`invoiceId`	字符串	必需	用于标识发票的唯一 24 位十六进制数字字符串。

请求正文参数

名称	类型	必要性	说明
`reportType`	字符串	必需	要生成的报告类型。必须设置为 `FOCUS`。
`reportFormat`	字符串	必需	报告的格式。允许的值：`CSV`。
`formatSpecVersion`	字符串	Optional	报告格式规范的版本，例如 `1.3`。

请求示例

curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --header "Content-Type: application/json" \
  --request POST "https://cloud.mongodb.com/api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports" \
  --data '{
    "reportType": "FOCUS",
    "reportFormat": "CSV",
    "formatSpecVersion": "1.3"
  }'

响应

成功后，返回 201 Created 和报告 ID 以及报告的初始状态：

{
  "invoiceId": "32b6e34b3d91647abb20e7b8",
  "reportFormat": "CSV",
  "reportId": "5f5f4c9e2b8f4b3a1c2d3e4f",
  "reportType": "FOCUS",
  "state": "PENDING"
}

要下载报告，请将返回的 reportId 传递给检索终结点。

检索 FOCUS 报告

返回您请求的 FOCUS 报告的状态和详细信息。投票此终结点，直到 state 为 SUCCEEDED 或 FAILED。

每五秒扫描一次。如果报告生成时间过长，请以指数方式增加请求之间的间隔。大多数报告在几秒内完成，但大额发票的报告可能需要几分钟。

基本 URL： /api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports/{reportId}

GET /api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports/{reportId}

请求路径参数

名称	类型	必要性	说明
`orgId`	字符串	必需	标识组织的唯一 24 位十六进制数字字符串。
`invoiceId`	字符串	必需	用于标识发票的唯一 24 位十六进制数字字符串。
`reportId`	字符串	必需	用于标识报告的唯一 24-十六进制位数字符串。

请求示例

curl --user "${PUBLIC_KEY}:${PRIVATE_KEY}" \
  --digest \
  --header "Accept: application/vnd.atlas.2025-03-12+json" \
  --request GET "https://cloud.mongodb.com/api/atlas/v2/orgs/{orgId}/invoices/{invoiceId}/reports/{reportId}"

响应

成功后，返回 200 OK 和报告的当前状态。当 state 为 SUCCEEDED 时，响应还包括下载 URL 及其过期时间：

{
  "downloadUrl": "https://<presigned-url>",
  "expiresAt": "2026-08-17T18:30:00Z",
  "formatSpecVersion": "1.3",
  "invoiceId": "32b6e34b3d91647abb20e7b8",
  "reportFormat": "CSV",
  "reportId": "5f5f4c9e2b8f4b3a1c2d3e4f",
  "reportType": "FOCUS",
  "state": "SUCCEEDED"
}

报告状态

州	说明
`PENDING`	Atlas 已接受请求，但尚未开始生成报告。
`RUNNING`	Atlas 正在生成报告。
`SUCCEEDED`	报告已就绪。响应包括 `downloadUrl` 和 `expiresAt`。
`FAILED`	Atlas无法生成报告。响应包括 `failureReason`。

响应元素

名称	类型	说明
`downloadUrl`	字符串	下载报告的 URL。仅当 `state` 为 `SUCCEEDED` 时，响应才包含此参数。
`expiresAt`	字符串	`downloadUrl` 到期的日期和时间，以 UTC 中的 ISO 8601 格式表示。每个下载 URL 在 15 分钟内有效。仅当 `state` 为 `SUCCEEDED` 时，响应才包含此参数。
`failureReason`	字符串	报告失败的原因。仅当 `state` 为 `FAILED` 时，响应才包含此参数。
`formatSpecVersion`	字符串	报告格式规范的版本。
`invoiceId`	字符串	用于标识发票的唯一 24 位十六进制数字字符串。
`reportFormat`	字符串	生成的报告格式。
`reportId`	字符串	用于标识报告的唯一 24-十六进制位数字符串。
`reportType`	字符串	生成报告的类型。
`state`	字符串	报告生成的当前状态。

报告可用性

每个 downloadUrl 的有效期为 15 分钟。要在 URL 过期后下载报告，请使用相同的 reportId 再次调用此终结点。Atlas 返回一个新的 downloadUrl 和一个新的 expiresAt 时间。

报告在您请求后可用七天。七天后，请求新报告以下载相同的发票数据。

数据行为和性能

以下部分介绍 FOCUS 数据 API 如何处理待处理数据和大规模报告生成。

待处理月可见性

您可以查询“待处理”（当前）月的数据。尽管 Atlas 实时将使用与信用关联起来以提供费用估算，但在发票关闭之前，这些值为 not final。月份关闭后重新拉取数据，以确认最终计费值。

处理大型数据的文件

FOCUS 数据 API 以旨在处理大规模计费数据的方式生成和交付报告：

异步生成： 报告生成不会阻塞您的请求。请求终结点会立即返回 reportId，您可以检索终结点以获取报告状态。
CSV 格式：报告以 CSV 文件的形式生成。
有时间限制的下载 URL：报告成功后，检索终结点将返回在 15 分钟内有效的 downloadUrl。报告可用七天。要了解如何刷新过期的 URL，请参阅《报告可用性》。
单组织范围：每个请求返回一个组织的数据。如果使用跨组织计费，请为列表终结点返回的每个 invoiceId 请求一份报告。

限制

该终结点仅涵盖基于使用量的费用。它目前不包括：
- 短缺费用（每月/灵活承诺差异）。
- 税收行项。
- 调整或退款。

要在 Atlas 控制台中查看完整的发票，请参阅管理发票。

支持和反馈

有关 FOCUS 数据 API 的问题，请联系 MongoDB 账户团队。要向其他开发者提问并参与讨论，请参阅 Stack Overflow 或 Reddit 上的 MongoDB 社区。

后退

国际使用费和税费

来年

探索您的数据