新商務每日評等使用量 v2 API （beta）
適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府適用的 Microsoft Cloud 合作夥伴中心
使用這些 API，以異步方式取得 每日已計費且未計費的新商務 使用量數據。
注意
此 API 即將淘汰。 請改用 GA 版本。 如需詳細資訊，請參閱下列詳細數據。
您只能在 2024 年 9 月 30 日之前，將此 API 用於每日評等使用量計費。 請參閱詳細數據，以預先選取正確的 API 版本和規劃。
- 儘快移至 v2 GA。 在此之前，使用此 API 來取得 2022 年 9 月起計費期間新商務發票的每日分級使用量明細專案。
- 僅使用從 2024 年 10 月 1 日開始的 API v2 GA，從 2022 年 9 月起取得新商務發票每日評等使用量明細專案。
您只能在 2024 年 9 月 30 日之前，將此 API 用於每日未計費的使用量。 請參閱詳細數據，以預先選取正確的 API 版本和規劃。
- 儘快移至 v2 GA。 在那之前，使用此 API 來取得 目前和先前計費期間每日未計費的每日評等使用量明細專案的新商務 。
- 僅使用 API v2 GA 從 2024 年 10 月 1 日開始，以取得目前和先前計費期間每日未計費的每日評等使用量明細專案。
若要存取新的 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 回應會包含 Retry-After 標頭，指出您應該在傳送另一個要求之前等候的時間。
指令清單端點
此端點提供可從中下載實際計費數據的記憶體資料夾。 回應會分割或分割檔案，以優化輸送量和 I/O 平行處理原則。
順序圖表
下圖描述下載對帳數據所需的步驟。
用戶動作順序
請遵循下列步驟來擷取對帳數據。
步驟 1：提交要求
將 POST 要求提交至 API 端點。
取得未計費的使用明細專案
取得目前或上一個行事曆月份未計費的使用明細專案。
API 要求
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
要求參數
| 名稱 | In | 必要 | 型別 | 說明 |
|---|---|---|---|---|
| fragment | 查詢 | False | String | 針對屬性子集選擇 [完整] 以取得完整的回應或 「基本」。 預設值為 「full」。。 請參閱本文中的屬性 清單。 |
| Period | 查詢 | True | String | 使用 「current」 或 「last」 取得目前或上一個行事曆月份的使用方式。 值 「last」 與現有 V1 API 中的 「previous」 相同。 |
| currencyCode | 查詢 | True | String | 合作夥伴計費貨幣代碼。 |
已淘汰的要求參數
較新的 API 版本不需要下列 URI 參數：
| 名稱 | 說明 |
|---|---|
| 提供者 | N/A。 （它會傳回所有 Azure 方案使用量，相當於現有 V1 API 的「一次性」。 |
| hasPartnerEarnedCredit | N/A。 （傳回所有數據，不論 PEC 為何。 |
| 大小 | N/A。 |
| 位移 | N/A。 |
| seekOperation | N/A。 |
要求標頭
請參閱本文中 API 的要求標頭清單。
要求本文
N/A。
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 可以傳回其他 標準狀態。
| 名稱 | 說明 |
|---|---|
| 202 已接受 | 已接受要求。 查詢要求狀態的作業位置標頭 URL。 |
取得計費的使用明細專案
取得已關閉計費週期的已計費使用量明細專案。
API 要求
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
要求參數
| 名稱 | In | 必要 | 型別 | 說明 |
|---|---|---|---|---|
| invoiceId | 路徑 | True | String | 合作夥伴中心發票號碼。 |
| Fragment | 查詢 | False | String | 針對屬性子集選擇 [完整] 以取得完整的回應或 「基本」。 預設值為 「full」。。 請參閱本文中的屬性 清單。 |
已淘汰的要求參數
較新的 API 版本不需要下列 URI 參數：
| 名稱 | 說明 |
|---|---|
| 提供者 | N/A。 （它會傳回所有 Azure 方案使用量，相當於現有 V1 API 的「一次性」。 |
| hasPartnerEarnedCredit | N/A。 （傳回所有數據，不論 PEC 為何。 |
| 大小 | N/A。 |
| 位移 | N/A。 |
| seekOperation | N/A。 |
要求標頭
請參閱本文中 API 的要求標頭清單。
要求本文
N/A。
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 Accepted」。。 根據要求 API 可以傳回其他 標準狀態。
| 名稱 | 說明 |
|---|---|
| 202 已接受 | 已接受要求。 輪詢作業位置標頭 URL 來檢查要求狀態。 |
步驟 2：檢查要求狀態
等候具有終端機狀態為成功或失敗的 HTTP 200。 指令清單 URL 將會是成功狀態中的 「resourceLocation」。。
取得作業狀態
取得對帳數據要求的狀態。
API 要求
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
要求參數
| 名稱 | In | 必要 | 型別 | 說明 |
|---|---|---|---|---|
| operationId | 路徑 | True | String | 作業標識碼。 |
要求標頭
請參閱本文中 API 的要求標頭清單。
要求本文
N/A。
回應狀態
除了 本文中的標準 HTTP 狀態 之外，API 還可以傳回下列 HTTP 狀態：
| 名稱 | 說明 |
|---|---|
| 410 消失 | 針對指定的伺服器控制時間，每個作業鏈接都會處於作用中狀態。 經過時間之後，客戶端必須提交新的要求。 |
回應承載
API 回應承載會傳回下列屬性：
| 名稱 | 選擇性 | 描述 |
|---|---|---|
| createdDateTime | false | 要求時間。 |
| lastActionDateTime | false | 狀態變更時間。 |
| resourceLocation | true | 指令清單承載 URI。 |
| status | false | 可能的值和動作。 |
| 值 | 用戶端動作 |
|---|---|
| notstarted | 進行另一個呼叫，以在等候 「Retry-After」 標頭中指定的時間之後檢查狀態。 |
| 執行中 | 進行另一個呼叫，以在等候 「Retry-After」 標頭中指定的時間之後檢查狀態。 |
| succeeded | 作業的最終狀態，表示數據已就緒。 使用 resourceLocation 中指定的 URI 擷取指令清單承載。 |
| 失敗 | 終端機狀態，表示永久失敗。 重新啟動作業。 |
針對錯誤屬性：
| 名稱 | 選擇性 | 描述 |
|---|---|---|
| error | true | 如果作業狀態失敗，則以 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}
要求參數
| 名稱 | In | 必要 | 型別 | 說明 |
|---|---|---|---|---|
| manifestId | 路徑 | True | String | 指令清單標識碼。 |
要求標頭
請參閱本文中的 [API 要求標頭清單]。
要求本文
N/A。
回應狀態
除了 標準 HTTP 狀態之外，API 還可以傳回下列 HTTP 狀態：
| 名稱 | 說明 |
|---|---|
| 410 消失 | 每個指令清單鏈接都會在指定的伺服器控制時間使用中。 經過時間之後，客戶端必須提交新的要求。 |
回應承載
API 回應會傳回下列屬性：
| 名稱 | 說明 |
|---|---|
| 版本 | 指令清單架構版本。 |
| dataFormat | 計費數據檔案格式。 可能的值 compressedJSONLines：每個 Blob 都是壓縮檔，而且檔案中的數據採用 JSON 行 格式。 解壓縮檔案以存取數據。 |
| utcCreatedDateTime | 指令清單檔案建立時間。 |
| eTag | 指令清單數據版本。 帳單資訊中的變更會產生新的 eTag 值。 |
| partnerTenantId | 合作夥伴租用戶標識碼。 |
| rootFolder | 檔案的根目錄。 |
| rootFolderSAS | 用於存取檔案的SAS令牌。 |
| partitionType | 這個屬性會分割數據。 如果指定的分割區數目超過支援的數字，數據將會分割成對應到 「partitionValue」 的多個檔案。根據預設，數據會依檔案中的明細項目數目來分割。 請勿在您的程式代碼中設定固定的行專案或檔案大小，因為這些專案可能會變更。 |
| blobCount | 此合作夥伴租用戶標識碼的檔案計數總計。 |
| sizeInBytes | 所有檔案中的位元組總數。 |
| Blob | 具有合作夥伴租用戶標識碼所有檔案詳細數據的 「blob」 物件的 JSON 陣列。 |
| Blob 物件 | |
| 名稱 | Blob 的名稱。 |
| sizeInBytes | 以位元組為單位的 Blob 大小。 |
| partitionValue | 包含檔案的分割區。 大型分割區將會分割成多個檔案，每個檔案都有相同的 「partitionValue」。。 |
範例指令清單承載
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"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 都接受下列標頭：
| 名稱 | 必要 | 型別 | 說明 |
|---|---|---|---|
| 授權 | True | String | 授權持有人令牌。 |
| ms-correlationid | False | String | 內部要求追蹤器。 每個要求都會產生新的追蹤器 （GUID）。 |
| ms-cv | False | String | 內部要求追蹤器。 |
| ms-requestid | False | String | 要求等冪標識碼。 |
標準 API 回應狀態
以下是來自 API 回應的 HTTP 狀態：
| 名稱 | 說明 |
|---|---|
| 400 不正確的要求 | 數據遺失或不正確。 錯誤詳細數據會包含在回應本文中。 |
| 401 未經授權 | 呼叫端未通過驗證，且必須先向合作夥伴 API 服務進行驗證，才能進行第一次呼叫。 |
| 403 禁止 | 呼叫端無權提出要求。 |
| 500 內部伺服器錯誤 | API 或其其中一個相依性無法滿足要求。 請稍後再試一次。 |
| 404 找不到 | 輸入參數無法使用資源。 |
| 410 消失 | 指令清單連結已逾時或已耗用。 提交新的要求。 |
使用量資料屬性
具有「完整」或「基本」要求參數的計費或未計費使用量 API 回應會傳回下列屬性：
| 屬性 | “full” | “basic” |
|---|---|---|
| PartnerId | 是 | 是 |
| PartnerName | 是 | 是 |
| CustomerId | 是 | 是 |
| CustomerName | 是 | Yes |
| CustomerDomainName | 是 | 否 |
| CustomerCountry | 是 | 否 |
| MpnId | 是 | 否 |
| Tier2MpnId | 是 | 否 |
| InvoiceNumber | 是 | 是 |
| ProductId | 是 | 是 |
| SkuId | 是 | 是 |
| AvailabilityId | 是 | 否 |
| SkuName | 是 | 是 |
| ProductName | 是 | 否 |
| PublisherName | 是 | 是 |
| PublisherId | 是 | 否 |
| SubscriptionDescription | 是 | 否 |
| SubscriptionId | 是 | 是 |
| ChargeStartDate | 是 | 是 |
| ChargeEndDate | 是 | 是 |
| UsageDate | 是 | 是 |
| MeterType | 是 | 否 |
| 計量類別目錄 | 是 | 否 |
| MeterId | 是 | 否 |
| MeterSubCategory | 是 | 否 |
| MeterName | 是 | 否 |
| MeterRegion | 是 | 否 |
| 單位 | 是 | 是 |
| 資源位置 | 是 | 否 |
| ConsumedService | 是 | 否 |
| ResourceGroup | 是 | 否 |
| ResourceURI | 是 | 是 |
| ChargeType | 是 | 是 |
| UnitPrice | 是 | 是 |
| 數量 | 是 | 是 |
| UnitType | 是 | 否 |
| BillingPreTaxTotal | 是 | 是 |
| BillingCurrency | 是 | 是 |
| PricingPreTaxTotal | 是 | 是 |
| PricingCurrency | 是 | 是 |
| ServiceInfo1 | 是 | 否 |
| ServiceInfo2 | 是 | 否 |
| 標籤 | 是 | 否 |
| AdditionalInfo | 是 | 否 |
| EffectiveUnitPrice | 是 | 是 |
| PCToBCExchangeRate | 是 | 是 |
| EntitlementId | 是 | 是 |
| EntitlementDescription | 是 | 否 |
| PartnerEarnedCreditPercentage | 是 | 否 |
| CreditPercentage | 是 | 是 |
| CreditType | 是 | 是 |
| BenefitOrderID | 是 | 是 |
| BenefitID | 是 | 否 |
| BenefitType | 是 | 是 |
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應