计费和未计费的每日分级使用情况对帐 API v2 （GA）

项目
02/09/2025

适用于：合作伙伴中心（Azure 政府或 Azure 中国世纪互联不可用）。

我们的新异步 API 提供了一种更快、更高效的方式来通过 Azure Blob 访问计费和对帐数据。与其保持连接数小时或处理 2,000 行数据项，现在您可以简化工作流、减少服务器负载，并加快数据处理速度。

新的商业每日分级使用情况对帐 API 使用辅助密钥和异步请求回复模式等高级技术。辅助密钥模式支持在不共享凭据的情况下安全访问资源，而异步请求-回复模式有助于在系统之间实现高效的通信。

这些 API 提供共享访问签名（SAS）令牌，可用于访问所有属性或每日分级使用情况对帐数据的子集。此令牌通过授予有限的时间访问权限来增强安全性，并提供管理数据访问权限的灵活性。

通过采用我们优化的 API，可以事半功倍地获得更快的结果，简化数据访问并提高整体效率。利用这些工具简化工作流并更有效地管理权限。

注意

新 API 不托管在合作伙伴中心 API 主机上。相反，可以在 MS Graph 上使用 Microsoft 图形 API 导出合作伙伴计费数据 - Microsoft Graph v1.0 |Microsoft Learn。若要访问这些 API，请参阅以下详细信息。

目前，只能将这些 API 用于 MS Graph 公有全局云。它们尚不适用于 Azure 政府版或 Azure 中国版。

允许应用访问合作伙伴计费数据

若要允许应用访问合作伙伴计费数据，请遵循此链接并熟悉 Microsoft Graph 的身份验证和授权基础知识。此步骤至关重要，因为它可确保应用能够安全地访问必要的数据。

分配 PartnerBilling.Read.All 权限

使用 Azure 门户或 Microsoft Entra 管理中心分配“PartnerBilling.Read.All”权限。这些步骤可确保你的应用有权访问合作伙伴计费数据。

在“应用注册”部分下的“Microsoft Entra 主页上注册应用。
转到“Microsoft Entra 应用”页，授予所需的权限。在 API 权限部分下，选择 添加权限 然后选择 PartnerBilling.Read.All 范围。

了解 beta 版本和 GA 版本之间的差异

如果你一直在使用我们的 beta 版本，则可能发现过渡到正式版（GA）版本流畅直观。为了帮助你了解更新和改进，我们建议比较 beta 版本和 GA 版本。了解这些更新有助于最大程度地提高 GA 版本中提供的新功能和改进。

重要

新的商业每日分级使用情况不包括这些产品的费用：

Azure 预留
Azure 节省计划
Office
Dynamics
Microsoft Power Apps
永久性软件
软件订阅
非Microsoft或市场 SaaS 产品

了解和使用 API 终结点

为了帮助你异步检索按计费 的新商务 每日分级使用行项，我们提供了两个关键 API 终结点。按照这份简化指南快速开始。

使用行项终结点

首先，使用此 API 提取 新的商业 每日分级使用行项。发出请求时，会收到 202 HTTP 状态和带有 URL 的位置标头。定期轮询此 URL，直到获得成功状态和清单 URL。

使用操作状态终结点

按照以下步骤，可以有效地管理发票对帐过程。

定期调用此 API 来继续检查作状态。如果数据尚未准备就绪，响应将包含一个 重试后 标头，指示在重试之前等待多长时间。作完成后，会收到包含存储文件夹链接的清单资源，用于下载使用情况数据。响应将文件分段以增强吞吐量并允许 I/O 并行。

下载对帐数据

下面是一个序列图，其中显示了下载对帐数据的步骤。

展示下载对账数据步骤的图表。

遵循用户操作顺序

下面是检索新商务每日额定使用量对帐行项的用户操作顺序步骤：

提交请求
检查请求状态
从 Azure Blob 存储下载每日额定使用量对帐行项

提交请求

将 POST 请求提交到 API 终结点。

获取每日未计费的使用情况行项

获取当前或上一个日历月或计费周期的每日未计费的每日计费使用情况行项。

注意

可以通过 API 或合作伙伴中心门户访问 未计费 的每日分级使用情况行项。为了确保数据准确性，请留出最多 24 小时的可用时间。根据你的位置以及计量报告使用情况的时间，可能会有进一步的延迟。

我们首先确定每日按计费使用情况数据的时间交付的优先级。有时，最新的未计费每日额定使用量数据可能要等到上个月的已计费数据可用后才会显示。收到已计费数据后，即可访问从月初开始的所有更新的未计费使用量数据。

要点：

数据可能需要最多24小时才能可用。
可能会有进一步延迟，具体取决于你的位置和计量报告时间。
已计费每日额定使用量数据优先于未计费数据。

由于我们努力提供最准确、最及时的信息，你对你的理解和耐心是值得赞赏的。

API 请求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

请求正文

属性	必需	类型	描述
attributeSet	False	字符串	为所有属性选择“full”，或为有限的集选择“basic”。如果未指定，则“full”是默认值。查看本部分中的属性列表。可选。
billingPeriod	True	字符串	若要获取每日未计费的使用量，请在当前计费周期中使用“current”，或在上一计费周期中使用“last”（相当于 v1 API 中的“previous”）。必需。
currencyCode	True	字符串	合作伙伴计费货币代码。必需。

请求标头

若要请求 API 的标头，请参阅可靠性和支持。

API 响应

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

API 通常以 HTTP 202 状态进行响应。可能还会遇到其他状态，具体取决于你的请求。这些状态列在 “标准 API 响应状态 ”部分。

代码	描述
202 - 已接受	你的请求已接受。若要检查请求的状态，请查询位置标头中提供的 URL。

每日按比例计费的使用情况行项

获取 已关闭计费周期发票的每日计费使用情况行项的新商务 计费。

API 请求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Query parameters

空值

请求正文

属性	必需	类型	描述
invoiceId	True	字符串	每个发票的唯一标识符。必需。
attributeSet	False	字符串	为所有属性选择“full”，或为有限的集选择“basic”。如果未指定，则“full”是默认值。查看本部分中的属性列表。可选。

请求头文件

请求 API 的标头。若要了解详细信息，请参阅可靠性和支持。

API 响应

HTTP/1.1 202 已接受
位置：https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

使用 API 时，它通常返回 HTTP 202 状态。有关基于你请求的其他可能状态，请参阅状态。

代码	描述
202 - 已接受	你的请求已接受。若要检查请求的状态，请查询位置标头中提供的 URL。

检查请求状态

若要跟踪请求的状态，请确保收到 HTTP 200 响应，这是指示“成功”或“失败”的标准状态代码。如果成功，可以在“resourceLocation”属性中找到清单 URL。此属性提供用于访问所需信息的终结点。

获取操作状态

检索请求的状态。

API 请求

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

请求参数

名称	包括	必需	类型	描述
operationId	请求 URI	True	字符串	用于检查请求状态的唯一标识符。必需。

请求头文件

若要请求 API 的标头，请参阅可靠性和支持。

请求正文

不适用。

响应状态

除了标准 API 响应状态中列出的标准 HTTP 状态之外，API 还可以返回以下 HTTP 状态：

代码	描述
410 - 消失	清单链接在设置时间后过期。若要再次获取清单链接，请发送一个新请求。

响应有效负载

API 响应有效负载包括以下属性：

属性	必需	描述
id	True	每个响应的唯一标识符。必需。
status	True	值和操作：必需： notstarted：等待“Retry-After”标头中的指定持续时间，然后再次调用以检查状态。 running：等待“Retry-After”标头中指定的持续时间，然后再次调用以检查状态。成功：数据已准备就绪。使用 resourceLocation 中指定的 URI 检索清单有效负载。失败：操作永久失败。重启它。
createdDateTime	True	发出请求的时间。必需。
lastActionDateTime	True	上次状态更改的时间。必需。
resourceLocation	False	清单有效负载的 URI。可选。
error	False	有关 JSON 格式提供的任何错误的详细信息。可选。包括的属性：消息：错误说明。代码：错误的类型。

资源位置对象

属性	描述
id	清单的唯一标识符。
schemaVersion	清单架构的版本。
dataFormat	计费数据文件的格式。 compressedJSON：数据格式，其中每个 Blob 都是包含 JSON 行格式数据的压缩文件。若要从每个 Blob 检索数据，请解压缩它。
createdDateTime	创建清单文件的日期和时间。
eTag	清单数据的版本。计费信息更改会生成新值。
partnerTenantId	Microsoft合作伙伴租户的 Entra ID。
rootDirectory	文件的根目录。
sasToken	SAS（共享访问签名）令牌，可用于读取目录下的所有文件。
partitionType	根据 “partitionValue” 属性将数据划分为多个 Blob。系统拆分超出支持数的分区。默认情况下，数据根据文件中的行项数进行分区。避免硬编码行项计数或文件大小，因为它们可能会更改。
blobCount	此合作伙伴租户 ID 的文件总数。
blobs	包含合作伙伴租户 ID 的文件详细信息的“blob”对象的 JSON 数组。
blob 对象	包含以下详细信息的对象：名称和partitionValue
name	blob 的名称。
partitionValue	包含文件的分区。大型分区根据某些标准（例如文件大小或记录数）拆分为多个文件，每个文件包含相同的“partitionValue”。

API 请求

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API 响应

响应建议在处理数据之前等待 10 秒。

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

API 请求

（上一个请求后的 10 秒...）

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

API 响应

API 返回“resourceLocation”的“成功”状态和 URI。

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

从 Azure Blob 存储下载每日额定使用量对帐行项

首先，需要获取共享访问签名（SAS）令牌和 Blob 存储位置。可以在清单有效负载 API 响应的 sasToken 和 rootDirectory 属性中找到这些详细信息。然后，若要下载和解压缩 blob 文件，请使用 Azure 存储 SDK/工具。它采用 JSONLines 格式。

提示

请务必查看我们的示例代码。它演示如何将 Azure Blob 文件下载并解压缩到本地数据库。

了解标准 API 响应状态

可以从 API 响应收到以下 HTTP 状态：

代码	描述
400 - 请求错误	请求缺失或包含不正确的数据。检查响应正文以了解错误详细信息。
401 - 未授权	在进行第一次调用之前，需要进行身份验证。使用合作伙伴 API 服务进行身份验证。
403 - 禁止	您没有发出请求所需的授权。
404 - 找不到	请求的资源不适用于提供的输入参数。
410 - 消失	清单链接不再有效或处于活动状态。提交新请求。
500 - 内部服务器错误	API 或其依赖项目前无法满足请求。请稍后重试。
5000 - 无可用数据	系统没有提供的输入参数的数据。

比较 beta 版本和 GA 版本

请查看以下比较表，了解 beta 版本与正式版（GA）版本之间的差异。如果当前使用的是测试版，那么过渡到正式版可能会非常简单。

重要信息	Beta	正式发布
API 主机终结点	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
HTTP 方法	POST	POST
每日未计费的已分级使用情况 API 终结点	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
未计费每日分级使用情况 API 的输入参数	若要在 API 请求中指定参数，请在请求 URL 的查询字符串中包含这些参数。例如，若要指定句点和 currencyCode 参数，请追加 `?period=current&currencyCode=usd` 到请求 URL。	若要提供输入，请在请求正文中包含 JSON 对象。 JSON 应具有以下属性： * currencyCode：计费货币。例如，USD。 * billingPeriod：发票的计费周期。例如，当前。下面是包含 currencyCode 和 billingPeriod 属性的示例 JSON 对象：`<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}`
按每日计费的使用情况 API 终结点	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
计费每日分级使用情况 API 的输入参数	若要在 API 请求中指定参数，请在请求 URL 中包含 invoiceId。此外，还可以在查询字符串中包含可选片段参数，以检索完整的属性集。例如，若要检索完整的属性集，请追加 `?fragment=full` 到请求 URL。	若要提供输入，请在请求正文中包含 JSON 对象。 JSON 应具有以下属性： * invoiceId：发票的唯一标识符。例如，G00012345。 * attributeSet：响应中应包含的属性，例如 full。下面是包含 invoiceId 和 attributeSet 属性的示例 JSON 对象： `{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}`
清单资源	使用单独的 GET /manifests/{id} 方法检索清单资源。	使用 GET /operations/{Id} 方法访问 resourceLocation 中的清单资源。此方法通过无需单独调用 GET /manifests/{id} 来节省时间。
对清单架构的更改
	“id”：不可用	“id”：清单资源的唯一标识符。
	“version”：可用	“version”：更改为“schemaversion”。
	“dataFormat”：可用	“dataFormat”：可用。
	“utcCretedDateTime”：可用	“utcCretedDateTime”：更改为“createdDateTime”。
	“eTag”：可用	“eTag”：可用。
	“partnerTenantId”：可用	“partnerTenantId”：可用
	“rootFolder”：可用	“rootFolder”：更改为“rootDirectory”。
	“rootFolderSAS”：可用	“rootFolderSAS”：更改为“sasToken”。此更新仅提供没有根目录路径的令牌。若要查找目录，请改用“rootDirectory”属性。
	“partitionType”：可用	“partitionType”：可用。
	“blobCount”：可用	“blobCount”：可用。
	“sizeInBytes”：可用	“sizeInBytes”：不可用。
	“blobs”：可用	“blobs”：可用。
	“blob 对象”：可用	“blob 对象”：可用。
	“name”：可用	“name”：可用。
	“partitionValue”：可用	“partitionValue”：可用。

比较每日额定使用量对帐行项属性

若要比较“完整”或“基本”属性集的已计费或未计费使用量对帐 API 返回的属性，请参阅此表。有关这些属性及其含义的详细信息，请参阅每日分级使用情况对帐文件中字段。

属性	完全	基本
PartnerId	是	是
PartnerName	是	是
CustomerId	是	是
CustomerName	是	是
CustomerDomainName	是	否
CustomerCountry	是	否
MpnId	是	否
Tier2MpnId	是	否
InvoiceNumber	是	是
ProductId	是	是
SkuId	是	是
AvailabilityId	是	否
SkuName	是	是
ProductName	是	否
PublisherName	是	是
PublisherId	是	否
SubscriptionDescription	是	否
SubscriptionId	是	是
ChargeStartDate	是	是
ChargeEndDate	是	是
UsageDate	是	是
MeterType	是	否
MeterCategory	是	否
MeterId	是	否
MeterSubCategory	是	否
MeterName	是	否
MeterRegion	是	否
单位	是	是
ResourceLocation	是	否
ConsumedService	是	否
ResourceGroup	是	否
ResourceURI	是	是
ChargeType	是	是
UnitPrice	是	是
数量	是	是
UnitType	是	否
BillingPreTaxTotal	是	是
BillingCurrency	是	是
PricingPreTaxTotal	是	是
PricingCurrency	是	是
ServiceInfo1	是	否
ServiceInfo2	是	否
Tags	是	否
AdditionalInfo	是	否
EffectiveUnitPrice	是	是
PCToBCExchangeRate	是	是
PCToBCExchangeRateDate	是	否
EntitlementId	是	是
EntitlementDescription	是	否
PartnerEarnedCreditPercentage	是	否
CreditPercentage	是	是
CreditType	是	是
BenefitOrderID	是	是
BenefitID	是	否
BenefitType	是	是

重要

在从 API v1 迁移到 v2 时，请记下这些更改。

每个属性名称现在均以大写字母开头，以保持与文件的一致性并提高可读性。
unitOfMeasure 已更新为 Unit。其含义和值保持不变，简化了属性名称。
resellerMpnId 现在是 Tier2MpnId。含义和值相同。
rateOfPartnerEarnedCredit 已更新为 PartnerEarnedCreditPercentage。 新的名称和值现在反映的是百分比而不是分数，从而更容易理解。例如，0.15 现在为 15%。
rateOfCredit 现在是 CreditPercentage。名称和值都已更改，以提供更清晰的理解。例如，1.00 现在为 100%。

我们相信这些更改使 API 更加直观且更易于使用。

获取示例代码

若要使用此 API，请参阅以下链接，其中包括 C# 示例代码。

合作伙伴中心 API 示例：获取计费对帐数据。

通过

计费和未计费的每日分级使用情况对帐 API v2 （GA）

允许应用访问合作伙伴计费数据

分配 PartnerBilling.Read.All 权限

了解 beta 版本和 GA 版本之间的差异

了解和使用 API 终结点

使用行项终结点

使用操作状态终结点

下载对帐数据

遵循用户操作顺序

提交请求

获取每日未计费的使用情况行项

API 请求

请求正文

请求标头

API 响应

每日按比例计费的使用情况行项

API 请求

请求正文

请求头文件

API 响应

检查请求状态

获取操作状态

API 请求

请求参数

请求头文件

请求正文

响应状态

响应有效负载

资源位置对象

API 请求

API 响应

API 请求

API 响应

从 Azure Blob 存储下载每日额定使用量对帐行项

了解标准 API 响应状态

比较 beta 版本和 GA 版本

比较每日额定使用量对帐行项属性

获取示例代码

反馈

其他资源