新商務每日評等使用量 v2 API （beta）
適用於：合作夥伴中心 |由 21Vianet 營運的合作夥伴中心 |美國政府Microsoft雲端合作夥伴中心
使用這些 API，以異步方式取得 每日已計費且未計費的新商務 使用量數據。
注意
此 API 即將淘汰。 為了確保順暢的作業，建議您移轉至 GA 版本。 以下是預先規劃所需的詳細數據：
目標：從 2025 年 1 月 21 日起，從 2022 年 9 月 21 日起擷取計費的每日評分使用量明細專案。
動作：使用此 API，但儘快移轉至 v2 GA。
目標：從 2025 年 1 月 21 日起，從 2022 年 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 回應會包含 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 | Query | False | String | 針對屬性子集選擇 [完整] 以取得完整的回應或 「基本」。 預設值為 「full」。。 請參閱本文中的屬性 清單。 |
| Period | Query | True | String | 使用 「current」 或 「last」 取得目前或上一個行事曆月份的使用方式。 值 「last」 與現有 V1 API 中的 「previous」 相同。 |
| currencyCode | Query | True | String | 合作夥伴計費貨幣代碼。 |
已淘汰的要求參數
較新的 API 版本不需要下列 URI 參數：
| 名稱 | 說明 |
|---|---|
| 提供者 | N/A。 （它會傳回所有 Azure 方案使用量，相當於現有 V1 API 的「一次性」。 |
| hasPartnerEarnedCredit | N/A。 （傳回所有數據，不論 PEC 為何。 |
| 大小 | N/A。 |
| Offset | 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 | Query | False | String | 針對屬性子集選擇 [完整] 以取得完整的回應或 「基本」。 預設值為 「full」。。 請參閱本文中的屬性 清單。 |
已淘汰的要求參數
較新的 API 版本不需要下列 URI 參數：
| 名稱 | 說明 |
|---|---|
| 提供者 | N/A。 （它會傳回所有 Azure 方案使用量，相當於現有 V1 API 的「一次性」。 |
| hasPartnerEarnedCredit | N/A。 （傳回所有數據，不論 PEC 為何。 |
| 大小 | N/A。 |
| Offset | 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": "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 都接受下列標頭：
| 名稱 | 必要 | 類型 | 說明 |
|---|---|---|---|
| 授權 | 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 | 是 | 是 |
| PCToBCExchangeRateDate | 是 | 否 |
| EntitlementId | 是 | 是 |
| EntitlementDescription | 是 | 否 |
| PartnerEarnedCreditPercentage | 是 | 否 |
| CreditPercentage | 是 | 是 |
| CreditType | 是 | 是 |
| BenefitOrderID | 是 | 是 |
| BenefitID | 是 | 否 |
| BenefitType | 是 | 是 |