帳單發票對帳 API v2 （GA）

發行項
03/07/2025

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

了解架構

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

主要元件

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

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

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

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

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

數據訪問許可權的彈性

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

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

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

好處

效能優點

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

透過 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"

}

查詢參數

N/A

請求主體

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

請求標頭

使用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	真的	String	檢查要求狀態的唯一標識碼。必要。

請求標頭

在使用 Microsoft Graph 的最佳作法中列出的步驟下請求 API 的標頭。遵循這些指導方針，可確保應用程式的可靠性和支援。在此步驟中，您對詳細數據的注意對於無縫整合和最佳效能至關重要。

請求主體

N/A。

回應狀態

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

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

回應負載

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

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

資源位置物件

屬性	描述
id	清單 (manifest) 的唯一識別碼。
schemaVersion	清單文件結構的版本。
資料格式	計費數據檔的格式。 compressedJSON：數據格式，其中每個 Blob 都是包含 JSON 行格式數據的壓縮檔。若要從每個 Blob 擷取數據，請將其解壓縮。
createdDateTime	建立清單文件的日期和時間。
eTag	清單資料的版本。每當帳單資訊有所變更時，就會產生新的值。
partnerTenantId	微軟合作夥伴租用戶端的 Entra 識別碼。
rootDirectory	檔案的根目錄。
sasToken	SAS（共用存取簽章）令牌，可讓您讀取目錄下的所有檔案。
分割類型	根據 partitionValue 屬性將數據分割成多個 Blob。系統會分割那些超過支援數目的磁碟分割區。根據預設，數據會根據檔案中的明細項目數目進行分割。避免將行項目計數或檔案大小硬編碼，因為它們可能會變更。
數據塊計數	此合作夥伴租戶 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 – 沒有可用的數據	系統沒有所提供輸入參數的數據。

比較基本和完整的發票對帳屬性

若要比較計費發票對帳 API 針對「完整」或「基本」屬性集所傳回的屬性，請參閱下表。若要深入瞭解這些屬性及其意義，請參閱如何使用對帳檔案。

屬性	完整	基本
PartnerId	是	是
客戶編號	是	是
客戶名稱	是	是
客戶域名	是	否
客戶國家	是	否
發票號碼	是	是
MpnId	是	否
Tier2MpnId	是	是
訂單編號	是	是
訂單日期	是	是
ProductId	是	是
SkuId	是	是
可用性ID	是	是
SkuName	是	否
ProductName	是	是
收費類型	是	是
單價	是	是
數量	是	否
小計	是	是
稅務總額	是	是
總數	是	是
貨幣	是	是
價格調整說明	是	是
PublisherName	是	是
出版商識別碼	是	否
訂閱描述	是	否
訂閱 ID	是	是
扣款開始日期	是	是
收費結束日期	是	是
期限與計費週期	是	是
有效單價	是	是
單位類型	是	否
AlternateId	是	否
可計費數量	是	是
計費頻率	是	否
定價貨幣	是	是
PCToBCExchangeRate	是	是
PC至BC匯率日期	是	否
計量器描述	是	否
預訂訂單編號	是	是
信用原因代碼	是	是
訂閱開始日期	是	是
訂閱結束日期	是	是
參考編號	是	是
ProductQualifiers	是	否
促銷編號 (PromotionId)	是	是
產品類別	是	是

重要

每個欄位或屬性名稱都會以大寫字母開頭，以維持檔案的一致性，並改善可讀性。

範例程序代碼

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

API 範例用於從合作夥伴中心取得帳單對帳資料。。

共用方式為

帳單發票對帳 API v2 （GA）

了解架構

主要元件

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

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

數據訪問許可權的彈性

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

好處

採用優化的 API 以提升效能

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

註冊您的應用程式並指派 PartnerBilling.Read.All 許可權

瞭解金鑰 API 端點

使用計費發票對帳端點

使用操作狀態端點

檢閱時序圖

遵循用戶動作順序來擷取帳單發票對帳數據

提交 POST 請求

取得帳單發票對帳明細項目

API 要求

查詢參數

請求主體

請求標頭

API 回應

檢查要求狀態

取得作業狀態

API 要求

要求參數

請求標頭

請求主體

回應狀態

回應負載

資源位置物件

API 要求

API 回應

API 要求

API 回應

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

標準 API 回應狀態

比較基本和完整的發票對帳屬性

範例程序代碼

相關內容

意見反應

其他資源