帳單發票對帳 API v2 （GA）

適用於： 合作夥伴中心（主權雲端無法使用）

我們的新異步 API 提供更快速且更有效率的方式，可讓您透過 Azure Blob 存取帳單和對帳數據。 與其讓網路連接保持開啟數小時或處理 2,000 筆條目，你現在可以通過簡化工作流程、減少伺服器負載來改善資料處理時間。

新的 商務計費發票對帳 API 會使用進階技術，例如 代客密鑰 和 異步要求-回復 模式。 代客鑰匙模式允許在不共用認證的情況下安全地存取資源，而異步請求-回復模式可讓系統之間有效地通訊。

此 API 提供共用存取簽章 （SAS） 令牌，可讓您用來存取所有屬性或帳單發票對帳數據的子集。 此令牌藉由授與有限的時間存取權來增強安全性，並提供管理數據訪問許可權的彈性。

藉由採用優化的 API，您可以透過較少的工作來達成更快的結果、簡化數據存取，並提升整體效率。 採用這些工具，以更有效率地簡化工作流程及管理許可權。

API 概觀

為了協助您以異步方式擷取已 計費的新商務 發票對帳明細專案，我們提供兩個主要 API 端點。 請遵循此簡化的指南，快速且有效率地開始使用！

計費發票對帳端點

首先，使用此 API 來擷取 新的商務 帳單發票對帳明細專案。 當您提出要求時，您會收到 202 HTTP 狀態和具有 URL 的位置標頭。 定期輪詢此 URL，直到您取得成功狀態和指令清單 URL 為止。

作業狀態端點

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

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

順序圖表

以下是一個順序圖，顯示下載新商務發票對帳數據的步驟。

用戶動作順序

若要擷取計費發票對帳數據，請遵循下列步驟：

步驟 1：提交要求

將 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

要求本文

要求標頭

使用使用 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 回應狀態 ] 區段中。

步驟 2：檢查要求狀態

若要追蹤要求的狀態，請確定您會收到 HTTP 200 回應，這是指出「成功」或「失敗」的標準狀態代碼。如果成功，您可以在 「resourceLocation」 屬性中找到指令清單 URL。 這個屬性提供存取必要資訊的端點。

取得作業狀態

擷取要求的狀態。

API 要求

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

要求參數

要求標頭

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

要求本文

N/A。

回應狀態

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

回應承載

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

資源位置物件

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"

            }

        \]

    }

}

步驟 3：從 Azure Blob 記憶體下載計費發票對帳明細專案

首先，您必須取得共用存取簽章 （SAS） 令牌和 Blob 記憶體位置。 您可以在指令清單承載 API 回應的 「sasToken」 和 「rootDirectory」 屬性中找到這些詳細數據。 然後，若要下載並解壓縮 Blob 檔案，請使用 Azure 儲存體 SDK/tool。 其格式為 JSONLines 。

標準 API 回應狀態

您可能會從 API 回應取得這些 HTTP 狀態：

帳單發票對帳明細項目屬性

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

範例指令碼

若要使用此 API，請參閱下列連結，其中包含 C# 範例程式代碼。

Partner-Center-Billing-Recon-Samples：用於從合作夥伴中心取得帳單對帳數據的 API 範例（github.com）。