已计费和未计费每日额定使用量对帐 API v2 (GA)

项目
02/25/2025

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

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

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

这些 API 为你提供了一个共享访问签名 (SAS) 令牌，可使用它访问所有特性或每日额定使用量对帐数据的子集。此令牌通过授予有限的时间访问权限来增强安全性，并提供管理数据访问权限的灵活性。

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

注意

新 API 不托管在合作伙伴中心 API 主机上。而你可以在 MS Graph 上的“使用 Microsoft Graph API 导出合作伙伴计费数据”处找到它们。若要访问这些 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 来继续检查作状态。如果数据尚未准备就绪，响应会包含一个 Retry-After 标头，指示在重试之前等待多长时间。作完成后，会收到包含存储文件夹链接的清单资源，用于下载使用情况数据。响应将文件分段以提高吞吐量并允许 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"  
}

查询参数

不适用

请求正文

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

资源位置对象

特性	说明
ID	清单的唯一标识符。
schemaVersion	清单架构的版本。
dataFormat	计费数据文件的格式。 compressedJSON：数据格式，此格式下每个 Blob 都是包含 JSON lines 格式数据的压缩文件。若要从每个 Blob 检索数据，请将它解压缩。
createdDateTime	创建清单文件的日期和时间。
eTag	清单数据的版本。账单信息更改会生成新值。
partnerTenantId	合作伙伴租户的 Microsoft Entra ID。
rootDirectory	文件的根目录。
sasToken	SAS（共享访问签名）令牌，可用于读取目录下的所有文件。
partitionType	根据“partitionValue”特性将数据划分为多个 Blob。系统拆分超出支持数的分区。默认情况下，数据根据文件中的行项数进行分区。避免硬编码行项计数或文件大小，因为它们可能会更改。
blobCount	此合作伙伴租户 ID 的文件总数。
blobs	包含合作伙伴租户 ID 的文件详细信息的“blob”对象的 JSON 数组。
blob object	包含以下详细信息的对象：name 和 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 返回“succeeded”状态和“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 的查询字符串中包含这些参数。例如，若要指定 period 和 currencyCode 参数，请向请求 URL 追加 `?period=current&currencyCode=usd`。	若要提供输入，请在请求正文中包含 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。此外，还可以在查询字符串中包含可选片段参数，以检索完整的特性集。例如，若要检索完整的特性集，请向请求 URL 追加 `?fragment=full`。	若要提供输入，请在请求正文中包含 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 object”：可用	“blob object”：可用。
	“name”：可用	“name”：可用。
	“partitionValue”：可用	“partitionValue”：可用。

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

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

特性	Full	Basic
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	是	否
Unit	是	是
ResourceLocation	是	否
ConsumedService	是	否
ResourceGroup	是	否
ResourceURI	是	是
ChargeType	是	是
UnitPrice	是	是
Quantity	是	是
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 版本

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

获取示例代码

相关内容

反馈

其他资源