新商业每日评级使用情况 v2 API （beta）
适用于：合作伙伴中心 | 由世纪互联运营的合作伙伴中心 | Microsoft Cloud for US Government 合作伙伴中心
使用这些 API 以异步方式获取每日计费和未计费的计费使用情况数据。
注意
此 API 即将弃用。 为了确保无缝操作，我们建议迁移到 GA 版本。 下面是提前计划所需的详细信息：
目标：从 2025 年 1 月 21 日之前检索计费周期的每日分级使用情况行项。
操作：使用此 API，但尽快迁移到 v2 GA。
目标：从 2025 年 9 月 21 日起检索计费周期的每日分级使用情况行项。
操作：仅使用 API v2 GA。
目标：在 2025 年 1 月 21 日之前检索当前和以前的计费周期的每日分级使用情况行项。
操作：使用此 API，但尽快迁移到 v2 GA。
目标：从 2025 年 1 月 21 日起检索当前和以前的计费周期的每日分级使用情况行项。
操作：仅使用 API v2 GA。
若要无缝过渡到新 API，请遵循以下链接：计费和未计费的每日分级使用情况对帐 API v2 （GA）。
感谢你的注意，我们期待着你继续成功使用我们的计费 API。
注意
可以通过 API 或合作伙伴中心门户访问 未计费 的每日分级使用情况行项。 为了确保准确的数据，最多允许 24 小时的可用性。 根据你的位置以及计量报告使用情况的时间，可能会有进一步的延迟。
我们首先确定每日按计费使用情况数据的时间交付的优先级。 有时，在前一个月的计费使用情况数据可用之前，可能不会看到最近 未计费 的每日使用量数据。 收到计费使用情况数据后，可以从本月初检索所有更新的未计费使用情况数据。
由于我们努力提供最准确、最及时的信息，你对你的理解和耐心是值得赞赏的。
重要
每日分级使用情况数据不包括这些产品的费用：
- Azure 预留
- Azure 节省计划
- Office
- Dynamics
- Microsoft Power Apps
- 永久性软件
- 软件订阅
- 非Microsoft或市场 SaaS 产品
API 概述
异步 API 是一种新方法，用于快速访问可管理区块中的计费和对帐数据。 它无需在数小时内保持开放连接，并循环访问数百万个事务。
我们使用 辅助密钥 和 异步请求-回复 模式来优化发票和对帐 API，以异步方式交付结果。 API 响应提供一个令牌，用于访问具有所有属性或子集的对帐数据。
可以使用三个新步骤（API 终结点）异步下载使用情况数据。 若要了解详细信息，请阅读以下部分：
使用行项终结点
使用此 API 访问计费或未计费的消耗行项。 它返回一个 202 HTTP 状态和一个带有 URL 的位置标头，你必须定期轮询该 URL，直到收到带有清单 URL 的成功状态。
操作状态终结点
在收到成功状态之前，请定期轮询此 API。 如果请求的数据不可用，API 响应将包含一个重试后标头，指示在发送另一个请求之前应等待多长时间。
清单终结点
此终结点提供一个存储文件夹，可从中下载实际计费数据。 响应拆分或分区文件以优化吞吐量和 I/O 并行度。
序列图
此图描述了下载对帐数据所需的步骤。
用户操作序列
按照以下步骤检索对帐数据。
步骤 1：提交请求
将 POST 请求提交到 API 终结点。
获取未计费的使用情况行项
获取当前或上一个日历月的未计费使用行项。
API 请求
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
请求参数
| Name | 位于 | 必需 | 类型 | 描述 |
|---|---|---|---|---|
| 片段 | 查询 | False | 字符串 | 为完整响应选择“full”，或为属性子集选择“basic”。 默认值为“full”。 请参阅本文中的属性 列表。 |
| period | 查询 | 正确 | 字符串 | 使用“current”或“last”获取当前或最后一个日历月的使用情况。 值“last”与现有 V1 API 中的“previous”相同。 |
| currencyCode | 查询 | 正确 | 字符串 | 合作伙伴计费货币代码。 |
已弃用的请求参数
较新的 API 版本不需要以下 URI 参数：
| Name | 描述 |
|---|---|
| 提供程序 | 不适用。 （它返回所有 Azure 计划使用情况，相当于现有 V1 API 的“一次性”。 |
| hasPartnerEarnedCredit | 不适用。 （返回所有数据，而不考虑 PEC。 |
| 大小 | 不适用。 |
| Offset | 不适用。 |
| seekOperation | 不适用。 |
请求头文件
请参阅本文中 API 的请求标头列表。
请求正文
不适用。
API 响应
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
API 返回 HTTP 状态 202。 根据请求，API 可以返回其他 标准状态。
| Name | 描述 |
|---|---|
| 202 已接受 | 接受请求。 查询请求状态的操作位置标头 URL。 |
获取计费的使用情况行项
获取已关闭计费周期的已计费使用情况行项。
API 请求
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
请求参数
| Name | 位于 | 必需 | 类型 | 描述 |
|---|---|---|---|---|
| invoiceId | 路径 | 正确 | 字符串 | 合作伙伴中心发票编号。 |
| Fragment | 查询 | False | 字符串 | 为完整响应选择“full”，或为属性子集选择“basic”。 默认值为“full”。 请参阅本文中的属性 列表。 |
已弃用的请求参数
较新的 API 版本不需要以下 URI 参数：
| Name | 描述 |
|---|---|
| 提供程序 | 不适用。 （它返回所有 Azure 计划使用情况，相当于现有 V1 API 的“一次性”。 |
| hasPartnerEarnedCredit | 不适用。 （返回所有数据，而不考虑 PEC。 |
| 大小 | 不适用。 |
| Offset | 不适用。 |
| seekOperation | 不适用。 |
请求头文件
请参阅本文中 API 的请求标头列表。
请求正文
不适用。
API 响应
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
API 返回“HTTP 202 已接受”。根据请求 API 可以返回其他 标准状态。
| Name | 描述 |
|---|---|
| 202 已接受 | 接受请求。 通过轮询操作位置标头 URL 来检查请求状态。 |
步骤 2：检查请求状态
等待终端状态为“成功”或“失败”的 HTTP 200。 清单 URL 是成功状态中的“resourceLocation”。
获取操作状态
获取对帐数据请求的状态。
API 请求
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
请求参数
| Name | 位于 | 必需 | 类型 | 描述 |
|---|---|---|---|---|
| operationId | 路径 | 正确 | 字符串 | 操作 ID。 |
请求头文件
请参阅本文中 API 的请求标头列表。
请求正文
不适用。
响应状态
除了 本文中的标准 HTTP 状态 之外，API 还可以返回此 HTTP 状态：
| Name | 描述 |
|---|---|
| 410 不存在 | 每个操作链接在指定的服务器控制时间内处于活动状态。 经过时间后，客户端必须提交新请求。 |
响应有效负载
API 响应有效负载返回以下属性：
| 名称 | 可选 | 说明 |
|---|---|---|
| createdDateTime | false | 请求时间。 |
| lastActionDateTime | false | 状态更改时间。 |
| resourceLocation | 是 | 清单有效负载 URI。 |
| status | false | 可能的值和操作。 |
| 值 | 客户端操作 |
|---|---|
| notstarted | 在等待“Retry-After”标头中指定的时间后，再次调用以检查状态。 |
| “正在运行” | 在等待“Retry-After”标头中指定的时间后，再次调用以检查状态。 |
| succeeded | 操作的最终状态，指示数据已就绪。 使用 resourceLocation 中指定的 URI 检索清单有效负载。 |
| 失败 | 终端状态，表示永久性故障。 重启操作。 |
对于错误属性：
| 名称 | 可选 | 说明 |
|---|---|---|
| error | 是 | 如果操作状态失败，则以 json 格式提供的错误详细信息。 |
| 名称 | 可选 | 说明 |
|---|---|---|
| message | false | 详细描述错误 |
| code | false | 指示发生的错误类型 |
API 请求
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API 响应
响应建议在处理数据之前等待 10 秒。
HTTP/1.1 200 OK
Retry-After: 10
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime":" 2022-06-1T10-01-05Z",
"status": "running"
}
API 请求
（上述请求后的 10 秒）
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
API 响应
API 返回“成功”状态和“resourceLocation”URI。
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
步骤 3：获取清单有效负载
调用方向清单 URL 发出 GET 请求，详细了解对帐数据存储在 Azure Blob 中的位置。
获取清单
检索清单，该清单包含有关对帐数据的 Azure 存储位置的信息。
API 请求
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
请求参数
| Name | 位于 | 必需 | 类型 | 描述 |
|---|---|---|---|---|
| manifestId | 路径 | 正确 | 字符串 | 清单 ID。 |
请求头文件
请参阅本文中的 [API 请求标头列表]。
请求正文
不适用。
响应状态
除了 标准 HTTP 状态之外，API 还可以返回此 HTTP 状态：
| Name | 描述 |
|---|---|
| 410 不存在 | 每个清单链接在指定的服务器控制时间内处于活动状态。 经过时间后，客户端必须提交新请求。 |
响应有效负载
API 响应返回以下属性：
| Name | 描述 |
|---|---|
| 版本 | 清单架构版本。 |
| dataFormat | 计费数据文件格式。 可能的值压缩JSONLines：每个 Blob 都是压缩的文件，文件中的数据采用 JSON 行 格式。 若要访问数据，请解压缩文件。 |
| utcCreatedDateTime | 清单文件创建时间。 |
| eTag | 清单数据版本。 计费信息更改会生成新的 eTag 值。 |
| partnerTenantId | 合作伙伴租户 ID。 |
| rootFolder | 文件的根目录。 |
| rootFolderSAS | 用于访问文件的 SAS 令牌。 |
| partitionType | 此属性将划分数据。 如果给定的分区数超过受支持的数字，则数据将拆分为对应于“partitionValue”的多个文件。默认情况下，系统根据文件中的行项数对数据进行分区。 不要在代码中设置固定数量的行项或文件大小，因为分区原则可能会更改。 |
| blobCount | 此合作伙伴租户 ID 的文件总数。 |
| sizeInBytes | 所有文件中的总字节数。 |
| blobs | 包含合作伙伴租户 ID 的所有文件的详细信息的“blob”对象的 JSON 数组。 |
| Blob 对象 | |
| 名称 | Blob 的名称。 |
| sizeInBytes | Blob 大小（以字节为单位）。 |
| partitionValue | 包含文件的分区。 大型分区将拆分为多个文件，每个文件具有相同的“partitionValue”。 |
示例清单有效负载
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
步骤 4：从存储位置下载使用情况对帐数据
从清单有效负载 API 响应获取“rootFolderSAS”和“rootFolder”属性中的 SAS 令牌和 Blob 存储位置。 使用 Azure 存储 SDK/tool 下载和解压缩 blob 文件。 它采用 JSON 行格式。
标准 API 请求标头
所有 API 都接受以下标头：
| Name | 必需 | 类型 | 描述 |
|---|---|---|---|
| 授权 | True | 字符串 | 授权持有者令牌。 |
| ms-correlationid | False | 字符串 | 内部请求跟踪器。 每个请求都会生成一个新的跟踪器（GUID）。 |
| ms-cv | False | 字符串 | 内部请求跟踪器。 |
| ms-requestid | False | 字符串 | 请求幂等 ID。 |
标准 API 响应状态
下面是 API 响应中的 HTTP 状态：
| Name | 描述 |
|---|---|
| 400 错误请求 | 数据缺失或不正确。 错误详细信息包含在响应正文中。 |
| 401 未授权 | 调用方未进行身份验证，必须在进行第一次调用之前向合作伙伴 API 服务进行身份验证。 |
| 403 禁止访问 | 调用方无权发出请求。 |
| 500 内部服务器错误 | API 或其依赖项之一无法满足请求。 请稍后重试。 |
| 404 未找到 | 输入参数不可用的资源。 |
| 410 不存在 | 清单链接超时或已用。 提交新请求。 |
使用情况数据属性
带有“full”或“basic”请求参数的计费或未计费使用情况 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 | 是 | 否 |
| 单位 | 是 | 是 |
| 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 | 是 | 是 |