计费发票对帐 API v2 (GA)

2025-02-26

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

了解体系结构

新的异步 API 在处理计费和对帐数据访问的方式方面具有重大进展。此方法解决了与传统同步方法相关的难题，例如维护长期连接和处理大型数据批处理。下面是此 API 的主要优势和机制：

关键组件

使用附属密钥模式保护访问

附属密钥模式可安全、有限地访问计费数据。类似于代客泊车钥匙允许某人在不打开后备箱的情况下驾驶汽车的功能，这种模式确保了精细化的访问控制。共享访问签名（SAS）令牌不共享凭据，而是授予对特定资源的有限时间限制访问权限。此模式通过配置精确的过期时间和访问权限来降低未经授权的访问风险。

通过异步请求-回复模式提高效率

把它想象成在繁忙的餐馆点菜。你无需在柜台前等待，而是会收到通知，你可以在订单准备过程中做其他事情。数据准备就绪后，系统会通知你。

API 的异步性质意味着发出请求，系统会在后台处理它。此异步请求-回复有效使用资源、减少服务器负载，并最大程度地减少同步数据检索常见的超时和故障。

数据访问权限的灵活性

SAS 令牌提供管理数据访问权限的灵活性。可以生成令牌，以授予对帐单发票对帐数据的所有属性的访问权限，或限制对特定子集的访问权限。这种粒度使组织能够根据内部策略和法规要求定制数据访问，从而提高安全性和合规性。

简化工作流和改进的数据处理时间

异步请求-回复模式通过允许动态访问来精简数据处理，而不是限制于固定批次的2,000行项目。此方法可更快地获得结果和改进的处理时间，从而简化计费和对帐数据与现有系统和工作流的集成。

好处

性能优势

新系统允许你进行以下操作，而不是维护长时间连接和处理固定批次：
- 发出快速的初始请求。
- 接收安全访问令牌。
- 按照自己的节奏处理数据。
- 随时随地准确访问所需内容。
安全性改进

通过 SAS 令牌实现的附属密钥模式可提供：
- 限时访问。
- 受限权限。
- 无需共享或存储永久凭据。
- 精细的访问控制。
体系结构优势

异步请求-回复模式类似于个人助理：
- 获取请求。
- 在后台处理任务。
- 在一切准备就绪时通知你。

采用优化的 API 以提高性能

采用这些优化的 API 可以简化工作流，并提高数据管理的整体性能。使用安全访问控制和高效的检索机制，可以降低工作量，从而获得更好的结果，从而提高运营效率。

总之，用于通过 Azure Blob 访问计费和对帐数据的新异步 API 是一个功能强大的工具。它提供对财务数据的安全、高效的访问、简化工作流、减少服务器负载以及提高处理时间，所有这些都具有较高的安全性和合规性。

注意

新 API 并非托管在合作伙伴中心 API 主机上。相反，你可以在 Microsoft Graph 上通过使用 Microsoft Graph API 导出合作伙伴计费数据 - Microsoft Graph v1.0 查找它。要访问此 API，请参阅以下详细信息。

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

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

注册应用并分配 PartnerBilling.Read.All 权限

可以使用 Azure 门户或 Microsoft Entra 管理中心分配“PartnerBilling.Read.All”权限。通过完成这些步骤，有助于确保应用有权访问合作伙伴计费数据。下面介绍如何操作：

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

了解主要 API 终结点

为了帮助你异步检索计费新商务发票对帐行项，我们提供了两个关键的 API 终结点。这些终结点可帮助你有效地管理发票对帐过程。按照这份简化指南快速开始。

使用计费发票对帐终结点

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

使用操作状态终结点

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

查看序列图

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

关系图，其中显示了下载对帐数据的步骤。

按照用户操作顺序检索计费发票对帐数据

以下是获取计费发票对账数据的用户操作顺序：

提交 POST 请求
检查请求状态
从 Azure Blob 存储下载对帐行项

提交 POST 请求

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

}

查询参数

暂缺

请求正文

属性	必需	类型	说明
attributeSet	False	字符串	若为全部属性则选择“完整”，若为一组有限的属性则选择“基本”。如果未指定，则默认是“完整”。查看本部分中的属性的列表。可选。
invoiceId	True	字符串	每张发票的唯一标识符。必需。

请求标头

使用适用于使用 Microsoft Graph 的最佳做法中列出的步骤请求 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。

检查请求状态

若要跟踪请求的状态，请确保收到 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 响应状态中列出的标准 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。可选。
error	False	错误相关的详细信息，以 JSON 格式提供。可选。包括的属性： message：错误的说明。 code：错误的类型。

资源位置对象

属性	说明
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 object	包含以下详细信息的对象：名称和 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 属性中找到这些详细信息。

要继续操作，请执行以下步骤：

使用 Azure 存储 SDK/工具下载 blob 文件。
解压缩文件，该文件采用 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	是	是
Quantity	是	否
Subtotal	是	是
TaxTotal	是	是
Total	是	是
Currency	是	是
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# 示例代码的链接。

API 示例，用于从合作伙伴中心获取计费对帐数据。

通过

计费发票对帐 API v2 (GA)

了解体系结构

关键组件

使用附属密钥模式保护访问

通过异步请求-回复模式提高效率

数据访问权限的灵活性

简化工作流和改进的数据处理时间

好处

采用优化的 API 以提高性能

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

注册应用并分配 PartnerBilling.Read.All 权限

了解主要 API 终结点

使用计费发票对帐终结点

使用操作状态终结点

查看序列图

按照用户操作顺序检索计费发票对帐数据

提交 POST 请求

获取计费发票对帐行项

API 请求

查询参数

请求正文

请求标头

API 响应

检查请求状态

获取操作状态

API 请求

请求参数

请求标头

请求正文

响应状态

响应有效负载

资源位置对象

API 请求

API 响应

API 请求

API 响应

从 Azure Blob 存储下载对帐行项

标准 API 响应状态

比较基本发票对帐属性和完整发票对帐属性

示例代码

相关内容

反馈

其他资源