計費和未計費的每日評等使用量對帳 API v2 （GA）

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

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

新的 商務每日評等使用量對帳 API 會使用進階技術，例如 代客密鑰 和 異步要求-回復 模式。 代客密鑰模式允許在不共用憑證的情況下安全地存取資源，而異步請求-回應模式使系統之間的通信更高效。

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

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

您現在只能將這些 API 用於 MS Graph 公用/全域雲端。 它們尚不適用於 Azure Government 或 Azure China 21Vianet。

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/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

要求本文

要求標頭

若要要求 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 回應狀態 ] 區段中。

取得每日評等使用量明細專案的計費

取得 已關閉計費期間發票的每日計費使用量明細專案的新商務 。

API 要求

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

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

查詢參數

N/A

要求本文

要求標頭

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

API 回應

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

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

步驟 2：檢查要求狀態

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

取得作業狀態

擷取要求的狀態。

API 要求

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

要求參數

要求標頭

若要要求 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 狀態：

比較 Beta 和 GA 版本

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

每日評分使用量對帳明細項目屬性

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

範例指令碼

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

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