計費和未計費的每日額定使用量核對 API v2 （GA）

發行項
03/07/2025

適用於： 合作夥伴中心（Azure Government 或 Azure China 21Vianet 中無法使用）

了解架構

新的異步 API 可大幅提升處理帳單和對帳數據存取的方式。此方法可解決與傳統同步方法相關聯的挑戰，例如維護長時間連線及處理大型數據批次。以下是此 API 的主要優點和機制：

主要元件

使用代客金鑰模式確保存取

valet key 模式提供安全且有限的帳單資料訪問權。類似於代客鑰匙允許某人駕駛您的汽車但無法存取後車廂，此模式可確保細緻的訪問控制。共用存取簽章（SAS）令牌不會共享認證，而是授與特定資源的有限時間限制存取權。此模式可藉由設定精確的到期時間和訪問許可權來降低未經授權的存取風險。

透過異步要求-回復模式提升效率

把它想像成在繁忙的餐廳點菜。您不會在櫃檯等候，而是收到蜂鳴器，而且可以在訂單準備就緒時做其他動作。當數據就緒時，系統會通知您。

API 的異步本質表示您提出要求，而系統會在背景中處理它。此異步要求-回復有效率地使用資源、減少伺服器負載，並將同步數據擷取常見的逾時和失敗降到最低。

數據訪問許可權的彈性

SAS 令牌提供管理數據訪問許可權的彈性。您可以產生令牌，授與帳單發票對帳數據之所有屬性的存取權，或限制特定子集的存取權。此數據粒度可讓組織根據內部原則和法規需求量身打造數據存取，增強安全性和合規性。

簡化工作流程並改善數據處理時間

異步請求-回覆模式透過允許動態存取而非固定批次2,000行項目，以簡化數據處理。這種方法可加快結果並改善處理時間，簡化帳單和對帳數據與現有系統和工作流程的整合。

優點

效能優點

新的系統不是維持長時間連線和處理固定批次，而是可讓您：
- 提出快速的初始要求。
- 接收安全存取令牌。
- 以您自己的步調處理數據。
- 需要時，即可精準取得所需內容。
安全性改善

透過 SAS 令牌實作的代客金鑰模式提供：
- 限時存取。
- 限制的許可權。
- 刪除共享或儲存永久認證。
- 精細存取控制。
建築架構優勢

非同步請求-回覆模式就像一位個人助理一樣：
- 受理您的请求。
- 在背景中處理工作。
- 當一切準備就緒時通知您。

採用優化的 API 以提升效能

採用這些優化的 API 可簡化工作流程，並增強數據管理的整體效能。使用安全訪問控制和有效率的擷取機制時，您能以較少的努力取得更好的結果，進而提升作業效率。

最後，透過 Azure Blob 存取計費和對帳數據的新異步 API 是功能強大的工具。它提供安全、有效率地存取財務數據、簡化工作流程、減少伺服器負載，以及改善處理時間，全都具有高安全性和合規性。

注意

新的 API 不會裝載在合作夥伴中心 API 主機上。相反地，您可以在 MS Graph 上找到它們，使用 Microsoft Graph API 匯出合作夥伴帳單資料。若要存取這些 API，請參閱下列詳細數據。

您目前只能將這些 API 用於 MS Graph 公用全域雲端。它們尚不適用於 Azure Government 或 Azure China。

允許您的應用程式存取合作夥伴帳單數據

若要允許您的應用程式存取合作夥伴帳單數據，請遵循此連結，並熟悉 Microsoft Graph 的驗證和授權基本概念。此步驟非常重要，因為它可確保您的應用程式可以安全地存取必要的數據。

指派 PartnerBilling.Read.All 權限

使用 Azure 入口網站或 Microsoft Entra 系統管理中心，指派 “PartnerBilling.Read.All” 許可權。這些步驟可確保您的應用程式具有合作夥伴帳單數據的必要存取權。

在 [應用程式註冊] 區段底下的 [Microsoft Entra 首頁上註冊您的應用程式。
移至 [Microsoft Entra 應用程式] 頁面，以授與必要的許可權。在 [API 許可權] 區段底下，選取 [[新增許可權]，然後選擇 [PartnerBilling.Read.All 範圍。

瞭解 Beta 和 GA 版本之間的差異

如果您一直在使用我們的 Beta 版本，您可能會發現轉換至正式運作（GA）版本順暢且直覺。為了協助您瞭解更新和改善，建議您比較 Beta 和 GA 版本。了解這些更新可協助您最大化 GA 版本中可用的新功能和改進功能。

重要

新商務的每日計費使用量不包含這些產品的費用：

Azure 預訂
Azure 節省方案
辦公室
動力學
Microsoft Power Apps
永久軟體
軟體訂閱
非 Microsoft 或市場的 SaaS 產品

瞭解及使用 API 端點

為了協助您以異步方式提取每日計費的新商務使用記錄項目，我們提供兩個主要的 API 端點。請遵循此簡化的指南來快速開始使用。

使用明細項端點

首先，使用此 API 來擷取 new commerce 每日使用量評分明細。當您發出請求時，您會收到 202 HTTP 狀態和包含 URL 的位置標頭。定期輪詢此 URL，直到您取得成功狀態並獲得清單 URL。

使用操作狀態端點

遵循這些步驟，您可以有效率地管理發票對帳程式。

定期呼叫此 API 以持續檢查作業狀態。如果數據尚未就緒，回應會包含 Retry-After 標頭，指出在再次嘗試之前要等候的時間。作業完成後，您會收到具有儲存資料夾連結的清單資源，以下載使用量數據。回應會將檔案分割以增強吞吐量，並允許 I/O 平行處理。

檢閱對帳數據順序圖表

以下順序圖表顯示下載對帳數據的步驟。

顯示下載對帳數據步驟的圖表。

遵循用戶動作順序

以下是取得新商務每日評估用量對帳項目的使用者操作步驟：

提交要求
檢查要求狀態
從 Azure Blob 儲存體下載對帳明細項目

提交要求

將 POST 要求提交至 API 端點。

取得每日未計費的用量明細項目

取得當前或上個曆月或計費週期中每日尚未計費的新商務使用量明細專案。

注意

您可以透過 API 或合作夥伴中心入口存取每日未結算的使用項目明細。為了確保數據正確性，最多允許 24 小時的可用性。視您的位置及計量報告使用量而定，可能會有進一步的延遲。

我們會先排定每日已計費使用量數據的時間傳遞的優先順序。有時候，最新的 尚未計費的 每日評等使用量數據可能要等到上個月的計費數據可用後才會顯示。收到計費數據之後，您就可以從本月初存取所有更新的未計費使用量數據。

關鍵點：

最多允許 24 小時的數據可用性。
視您的位置和計量報告時間而定，可能會有進一步的延遲。
每日計費的使用率數據會優先於未計費的數據。

由於我們努力盡可能提供最準確且最及時的資訊，您的理解和耐心是值得讚賞的。

API 要求

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

請求正文

屬性	必要	類型	描述
屬性集	錯誤	字串	針對有限的集合，選擇所有屬性的 [完整] 或 [基本]。如果未指定，“full” 是預設值。請檢查本節中的屬性清單，。選擇性。
帳單週期	真	字串	若要取得未計費的每日使用量統計，請在目前的計費期間使用「目前」，或針對上一個計費期間使用「上次」（與 v1 API 中的「上一個」相同）。必要。
貨幣代碼	真	字串	合作夥伴計費貨幣代碼。必要。

要求標頭

若要要求 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。

取得每日計價使用量明細項目的計費

在關閉的計費期間，取得發票中新商務的每日計費使用量項目。

API 要求

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

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

查詢參數

N/A

請求主體

屬性	必要	類型	描述
發票編號	正確	string	每個發票的唯一標識碼。必要。
屬性集合	錯誤	字串	針對有限的集合，選擇所有屬性的 [完整] 或 [基本]。如果未指定，“full” 是預設值。請檢查本節中的屬性清單，。選擇性。

要求標頭

要求 API 的標頭。若要深入瞭解，請參閱可靠性和支援。

API 回應

HTTP/1.1 202 已接受
位置：https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

當您使用 API 時，通常會傳回 HTTP 202 狀態。如需以您的要求為基礎的其他可能狀態，請參閱狀態。

代碼	描述
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	真	字串	檢查要求狀態的唯一標識碼。必要。

請求標頭

若要要求 API 的標頭，請參閱可靠性和支援。

請求正文

N/A。

回應狀態

除了標準 API 回應狀態中列出的標準 HTTP 狀態之外，API 也可以傳回下列 HTTP 狀態：

代碼	描述
410 - 消失	清單連結會在設定時間後到期。若要再次取得資訊檔連結，請傳送新的要求。

回應載荷

API 回應承載包含下列屬性：

屬性	必要	描述
識別碼	真	每個回應的唯一標識碼。必要。
狀態	真實	值和動作：必要： notstarted：等候 “Retry-After” 標頭中指定的持續時間，然後進行另一個呼叫來檢查狀態。執行：等候 “Retry-After” 標頭中指定的持續時間，然後再次進行呼叫以檢查狀態。成功：數據已就緒。使用resourceLocation中指定的 URI 擷取清單承載。 failed：作業永久失敗。重新啟動它。
createdDateTime	正確的	提出要求的時間。必要。
最後操作日期時間	正確	上次狀態變更的時間。必要。
資源位置	錯誤	清單文件的 URI。選擇性。
錯誤	錯誤	提供以 JSON 格式呈現的任何錯誤的詳細資訊。選擇性。包含的屬性：訊息：錯誤的描述。 code：錯誤的類型。

資源位置對象

屬性	描述
id	指令清單的唯一標識碼。
schemaVersion	清單架構的版本。
資料格式	計費數據檔的格式。 compressedJSON：數據格式，其中每個 Blob 都是包含 JSON 行格式數據的壓縮檔。若要從每個 Blob 擷取數據，請將其解壓縮。
createdDateTime	建立清單檔案的日期和時間。
eTag	清單數據的版本。帳單資訊中的變更會產生新的值。
partnerTenantId	Microsoft 夥伴租戶的 Entra ID。
rootDirectory	檔案的根目錄。
sasToken	SAS（共用存取簽章）令牌，可讓您讀取目錄下的所有檔案。
分區類型	根據「partitionValue」屬性將數據分割成多個 Blob。系統會分割超過支援數目的分割區。根據預設，數據會根據檔案中的明細項目數目進行分割。避免對項目數量和檔案大小進行固定，因為它們可能會改變。
blobCount	此合作夥伴租戶 ID 的檔案總數。
斑點或塊狀物	“blob” 物件的 JSON 陣列，其中包含夥伴租用戶識別碼的檔案詳細資訊。
blob 物件	物件，包含下列詳細數據： name 和 partitionValue
名字	Blob 的名稱。
分區值	包含檔案的分割區。大型分割區會根據特定準則分割成多個檔案，例如檔案大小或記錄數目，每個檔案都包含相同的 “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 儲存體位置（即根目錄與 Blob 名稱的組合）。您可以在指令清單承載 API 回應的 sasToken、rootDirectory和 blobs 屬性中找到這些詳細數據。

若要繼續進行，請遵循下列步驟：

使用 Azure 記憶體 SDK/工具下載 Blob 檔案。
解壓縮檔案，其格式為 JSONLines 格式。

提示

請參閱範例程式代碼。它示範如何將 Azure Blob 檔案下載並解壓縮至本機資料庫。

了解標準 API 回應狀態

您可能會從 API 回應收到這些 HTTP 狀態：

代碼	說明
400 - 錯誤請求	要求遺失或包含不正確的數據。請檢查回應內容以取得錯誤詳細資訊。
401 - 未經授權	進行第一次呼叫之前，必須先進行驗證。使用合作夥伴 API 服務進行驗證。
403 - 禁止	您沒有提出要求的必要授權。
404 - 找不到	所提供的輸入參數無法獲得所要求的資源。
410 - 消失	清單連結已不再有效或啟用。提交新的要求。
500 - 內部伺服器錯誤	API 或其相依性目前無法滿足要求。請稍後再試一次。
5000 - 沒有可用的數據	系統沒有所提供輸入參數的數據。

比較 Beta 和 GA 版本

請查看下列比較表，以查看 Beta 和正式推出版本之間的差異。如果您目前使用 Beta 版本，則轉換至 GA 版本可能很簡單且容易。

重要資訊	Beta	正式推出
API 主機端點	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
HTTP 方法	貼文	POST
未計費的每日評估使用量 API 端點	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
未計費每日使用量評等 API 的輸入參數	若要在 API 要求中指定參數，請在要求 URL 的查詢字串中包含這些參數。例如，若要指定 period 和 currencyCode 參數，請將附加 `?period=current&currencyCode=usd` 至要求 URL。	若要提供輸入，請在要求本文中包含 JSON 物件。您的 JSON 應該具有下列屬性： * currencyCode：您的計費貨幣。例如，美元。 * billingPeriod：發票的計費週期。例如，目前的情況。以下是包含 currencyCode 和 billingPeriod 屬性的範例 JSON 物件：`<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}`
每日計費使用量 API 端點	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
每日計費評估使用量 API 的輸入參數	若要在 API 要求中指定參數，請在要求 URL 中包含 invoiceId。此外，您可以在查詢字串中包含選擇性片段參數，以擷取完整的屬性集。例如，若要擷取完整的屬性集，請將附加 `?fragment=full` 至要求URL。	若要提供輸入，請在要求本文中包含 JSON 物件。您的 JSON 應該具有下列屬性： * invoiceId：發票的唯一標識符。例如，G00012345。 * attributeSet：應該在回應中的屬性，例如 full。以下是包含 invoiceId 和 attributeSet 屬性的範例 JSON 物件： `{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}`
清單資源	使用單獨的 GET /manifests/{id} 方法來擷取清單資源。	使用 GET /operations/{Id} 方法來存取 resourceLocation 中的指令清單資源。此方法可藉由不需要個別呼叫 GET /manifests/{id}來節省時間。
清單結構的變更
	“id”：無法使用	「id」：清單資源的唯一標識符。
	“version”：可用	“version”：已變更為 “schemaversion”。
	“dataFormat”：可用	“dataFormat”：可用。
	“utcCretedDateTime”：可用	“utcCretedDateTime”：已變更為 “createdDateTime”。
	“eTag”：可用	“eTag”：可用。
	“partnerTenantId”：可用	“partnerTenantId”：可用
	“rootFolder”：可用	“rootFolder”：已變更為 “rootDirectory”。
	“rootFolderSAS”：可用	“rootFolderSAS”：已變更為 “sasToken”。此更新只提供沒有根目錄路徑的令牌。若要尋找目錄，請改用「rootDirectory」屬性。
	“partitionType”：可用	“partitionType”：可用。
	“blobCount”：可用	“blobCount”: 可用。
	“sizeInBytes”：可用	“sizeInBytes”：無法取得。
	“blobs”：可用	“blobs”：可用。
	“blob 物件”：可用	“blob 物件”：可用。
	“name”：可用的	“name”：可用。
	“partitionValue”：可用	“partitionValue”：可用。

比較基本和完整每日日用量調整屬性

若要比較計費或未計費使用量對帳 API 針對「完整」或「基本」屬性集所傳回的屬性，請參閱下表。如需這些屬性及其意義的詳細資訊，請參閱每日評等使用量對帳檔案中的字段。

屬性	完整	基本
PartnerId	是	是
PartnerName	是	是
客戶編號	是	是
CustomerName	是	Yes
客戶網域名稱	是	否
顧客國家	是	否
MpnId	是	否
Tier2MpnId	是	否
發票號碼	是	是
ProductId	是	是
SkuId	是	是
AvailabilityId (可用性ID)	是	否
SkuName	是	是
ProductName	是	否
PublisherName	是	是
發行商ID	是	否
訂閱描述	是	否
訂閱ID	是	是
計費開始日期	是	是
收費結束日期	是	是
使用日期	是	是
儀表類型	是	否
計量類別	是	否
MeterId	是	否
計量器子類別	是	否
計量器名稱	是	否
MeterRegion	是	否
單位	是	是
資源位置	是	否
ConsumedService	是	否
ResourceGroup	是	否
ResourceURI	是	是
收費類型	是	是
單價	是	是
數量	是	是
單位類型	是	否
計費稅前總額	是	是
計費貨幣	是	是
定價稅前總額	是	是
定價貨幣	是	是
ServiceInfo1	是	否
ServiceInfo2	是	否
標籤	是	否
附加資訊	是	否
有效單價	是	是
從PC到BC的匯率	是	是
PCToBCExchangeRateDate	是	否
授權ID	是	是
權益描述	是	否
夥伴獲得的信用百分比	是	否
信用百分比	是	是
信用類型	是	是
福利訂單編號	是	是
福利ID	是	否
福利類型	是	是

重要

從 API v1 移至 v2 時，請記下這些變更。

每個屬性名稱的開頭都是大寫字母，以維持檔案的一致性，並改善可讀性。
unitOfMeasure 已更新為 Unit。其意義和值保持不變，可簡化屬性名稱。
resellerMpnId 現在是 Tier2MpnId。意義和值相同。
rateOfPartnerEarnedCredit 會更新為 PartnerEarnedCreditPercentage。新的名稱和值會反映百分比，而不是分數，讓您更容易瞭解。例如，0.15 現在是15%。
rateOfCredit 現在是 CreditPercentage。名稱和值都已變更，以提供更清楚的瞭解。例如，1.00 現在是100%。

我們相信這些變更可讓 API 更直覺且更容易使用。

範例程序代碼

如果您需要移轉至此 API 的協助，請參閱包含 C# 範例程式代碼的連結。

合作夥伴中心 API 範例：取得帳單對帳數據。

共用方式為

計費和未計費的每日額定使用量核對 API v2 （GA）

了解架構

主要元件

使用代客金鑰模式確保存取

透過異步要求-回復模式提升效率

數據訪問許可權的彈性

簡化工作流程並改善數據處理時間

優點

採用優化的 API 以提升效能

允許您的應用程式存取合作夥伴帳單數據

指派 PartnerBilling.Read.All 權限

瞭解 Beta 和 GA 版本之間的差異

瞭解及使用 API 端點

使用明細項端點

使用操作狀態端點

檢閱對帳數據順序圖表

遵循用戶動作順序

提交要求

取得每日未計費的用量明細項目

API 要求

請求正文

要求標頭

API 回應

取得每日計價使用量明細項目的計費

API 要求

請求主體

要求標頭

API 回應

檢查要求狀態

取得作業狀態

API 要求

要求參數

請求標頭

請求正文

回應狀態

回應載荷

資源位置對象

API 要求

API 回應

API 要求

API 回應

從 Azure Blob 儲存體下載對帳項目

了解標準 API 回應狀態

比較 Beta 和 GA 版本

比較基本和完整每日日用量調整屬性

範例程序代碼

相關內容

意見反應

其他資源