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

项目
11/06/2024

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

我们的新异步 API 提供了一种更快、更高效的方式来通过 Azure Blob 访问计费和对帐数据。现在可以简化工作流，而不是将连接保持打开数小时或处理 2,000 行项的批处理。

新的商业每日分级使用情况对帐 API 使用辅助密钥和异步请求回复模式等高级技术。这些 API 提供共享访问签名（SAS）令牌，可用于访问所有属性或每日分级使用情况对帐数据的子集。

我们的 API 使用优化的技术来提高效率，因此你可以以更少的工作量获得更快的结果。采用这些 API 来简化数据访问并提高整体效率。

注意

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

你现在只能将这些 API 用于 MS Graph 公有/全局云。它们尚不可用于 Azure 政府或 Azure 中国世纪互联。

重要

若要允许应用访问合作伙伴计费数据，请遵循此链接并熟悉 Microsoft Graph 的身份验证和授权基础知识。

可以使用 Azure 门户或 Entra 管理中心分配“PartnerBilling.Read.All”权限。操作步骤如下：

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

通过完成这些步骤，可确保应用对合作伙伴计费数据具有所需的访问权限。

注意

如果你一直在使用我们的 beta 版本，则可能发现过渡到正式版（GA）版本流畅直观。为了帮助你了解更新和改进，我们建议比较 beta 版本和 GA 版本。

重要

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

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

API 概述

为了帮助你异步检索按计费 的新商务 每日分级使用行项，我们提供了两个关键 API 终结点。下面是一个简化的入门指南：

使用行项终结点

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

操作状态终结点

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

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

序列图

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

显示下载对帐的步骤的关系图。

用户操作序列

若要检索 新的商业 每日分级使用情况对帐行项，请执行以下步骤：

步骤 1：提交请求

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

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

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

注意

可以通过 API 或合作伙伴中心门户访问 未计费 的每日分级使用情况行项。为了确保准确的数据，最多允许 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 中的“上一个”相同）。必需。
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。

步骤 2：检查请求状态

若要跟踪请求的状态，请确保收到指示“成功”或“失败”的 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”标头中指定的时间，然后进行另一个调用来检查状态。运行：等待“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": "0e195b37-4574-4539-bc42-0e539b9684c0",

        "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"

            }

        \]

    }

}

步骤 3：从 Azure Blob 存储下载每日分级使用情况对帐行项

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

提示

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

标准 API 响应状态

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

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

比较 beta 版本和 GA 版本

请查看比较表，了解 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	是	是

重要

从 v2 从 API v1 移动时，请记下这些更改。

每个属性名称现在以大写字母开头。
unitOfMeasure 已更新为 Unit。其含义和价值保持不变。
resellerMpnId 现在是 Tier2MpnId。含义和值相同。
rateOfPartnerEarnedCredit 已更新为 PartnerEarnedCreditPercentage。 新名称和值现在反映百分比而不是分数。例如，0.15 现在为 15%。
rateOfCredit 现在是 CreditPercentage。名称和值都已更改。例如，1.00 现在为 100%。

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

代码示例

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

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

通过

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

API 概述

使用行项终结点

操作状态终结点

序列图

用户操作序列

步骤 1：提交请求

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

API 请求

请求正文

请求标头

API 响应

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

API 请求

请求正文

请求头文件

API 响应

步骤 2：检查请求状态

获取操作状态

API 请求

请求参数

请求头文件

请求正文

响应状态

响应有效负载

资源位置对象

API 请求

API 响应

API 请求

API 响应

步骤 3：从 Azure Blob 存储下载每日分级使用情况对帐行项

标准 API 响应状态

比较 beta 版本和 GA 版本

每日分级使用情况对帐行项属性

代码示例

反馈

其他资源