计费发票对帐 API v2 （GA）

项目
10/31/2024

适用于： 合作伙伴中心（主权云中不可用）

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

新的商务计费发票对帐 API 使用辅助密钥和异步请求-回复模式等高级技术。此 API 提供共享访问签名（SAS）令牌，可用于访问所有属性或计费发票对帐数据的子集。

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

注意

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

重要

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

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

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

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

API 概述

为了帮助你异步检索计费 的新商务 发票对帐行项，我们提供了两个关键 API 终结点。下面是一个简化的入门指南：

计费发票对帐终结点

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

操作状态终结点

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

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

序列图

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

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

用户操作序列

若要检索计费的发票对帐数据，请执行以下步骤：

步骤 1：提交请求

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

获取计费发票对帐行项

API 请求

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

Accept: application/json

Content-Type: application/json

{

"invoiceId": "G016907411",

"attributeSet": "basic"

}

Query parameters

空值

请求正文

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

请求标头

使用最佳做法中列出的步骤为 API 请求标头，以使用 Microsoft Graph。遵循这些准则可确保应用程序的可靠性和支持。你对此步骤中细节的关注对于无缝集成和最佳性能至关重要。

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。

步骤 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	字符串	用于检查请求状态的唯一 ID。必需。

请求头文件

请求正文

不适用。

响应状态

除了标准 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 对象	包含以下详细信息的对象： 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 返回“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 – 无可用数据	系统没有提供的输入参数的数据。

计费发票对帐行项属性

若要比较“完整”或“基本”属性集的计费发票对帐 API 返回的属性，请参阅下表。若要了解有关这些属性的详细信息，请参阅 “使用对帐文件”。

属性	完全	基本
PartnerId	是	是
CustomerId	是	是
CustomerName	是	是
CustomerDomainName	是	否
CustomerCountry	是	否
InvoiceNumber	是	是
MpnId	是	否
Tier2MpnId	是	是
OrderId	是	是
OrderDate	是	是
ProductId	是	是
SkuId	是	是
AvailabilityId	是	是
SkuName	是	否
ProductName	是	是
ChargeType	是	是
UnitPrice	是	是
数量	是	否
小计	是	是
TaxTotal	是	是
总计	是	是
货币	是	是
PriceAdjustmentDescription	是	是
PublisherName	是	是
PublisherId	是	否
SubscriptionDescription	是	否
SubscriptionId	是	是
ChargeStartDate	是	是
ChargeEndDate	是	是
TermAndBillingCycle	是	是
EffectiveUnitPrice	是	是
UnitType	是	否
AlternateId	是	否
BillableQuantity	是	是
BillingFrequency	是	否
PricingCurrency	是	是
PCToBCExchangeRate	是	是
PCToBCExchangeRateDate	是	否
MeterDescription	是	否
ReservationOrderId	是	是
CreditReasonCode	是	是
SubscriptionStartDate	是	是
SubscriptionEndDate	是	是
ReferenceId	是	是
ProductQualifiers	是	否
PromotionId	是	是
ProductCategory	是	是

代码示例

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

Partner-Center-Billing-Recon-Samples：用于从合作伙伴中心获取计费对帐数据的 API 示例（github.com）。

通过

计费发票对帐 API v2 （GA）

API 概述

计费发票对帐终结点

操作状态终结点

序列图

用户操作序列

步骤 1：提交请求

获取计费发票对帐行项

API 请求

Query parameters

请求正文

请求标头

API 响应

步骤 2：检查请求状态

获取操作状态

API 请求

请求参数

请求头文件

请求正文

响应状态

响应有效负载

资源位置对象

API 请求

API 响应

API 请求

API 响应

步骤 3：从 Azure Blob 存储下载计费发票对帐行项

标准 API 响应状态

计费发票对帐行项属性

代码示例

反馈

其他资源