帳單發票對帳 API v2 （GA）

發行項
05/13/2024

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

我們的異步 API 提供更快速且更容易管理的方式，以透過 Azure Blob 存取計費和對帳數據。使用此 API 時，您不需要讓連線保持開啟數小時，或一次循環處理 2,000 個明細專案的批次。

我們已使用代客密鑰和異步要求-回復模式，將新的商務計費發票對帳 API 優化。此 API 提供共用存取簽章（SAS）令牌，可讓您用來存取所有屬性或帳單發票對帳數據的子集。

注意

新的 API 不會裝載於合作夥伴中心 API 主機上。相反地，您可以在 MS Graph 上找到它：使用 Microsoft Graph API 導出合作夥伴帳單數據 - Microsoft Graph v1.0。若要存取此 API，請參閱下列詳細數據。

您現在只能針對 MS Graph 公用/全域雲端使用此 API。 Azure Government、Azure 德國或 Azure China 21Vianet 尚無法使用。

API 概觀

若要以異步方式擷取計費 的新商務 發票對帳數據，請使用兩個 API 端點。程序如下：

計費發票對帳端點

使用此 API 來擷取 新的商務 帳單發票對帳明細專案。 API 會傳回 202 HTTP 狀態和包含 URL 的位置標頭。定期輪詢此 URL，直到您收到具有指令清單 URL 的成功狀態為止。

作業狀態端點

若要取得成功狀態，請定期呼叫此 API。如果數據尚未就緒，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

要求本文

屬性	必要	類型	描述
attributeSet	False	String	針對有限的集合，選擇所有屬性的 [完整] 或 [基本]。預設值為「full」。。（請參閱本文中的屬性清單）。選擇性。
invoiceId	True	String	每個發票的唯一標識碼。必要。

要求標頭

使用使用 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。

步驟 2：檢查要求狀態

若要檢查要求的狀態，請等候狀態為「成功」或「失敗」的 HTTP 200 回應。如果要求成功，您會在「resourceLocation」屬性中取得指令清單 URL。

取得作業狀態

擷取要求的狀態。

API 要求

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

要求參數

名稱	包含於	必要	類型	描述
operationId	要求 URI	True	String	檢查要求狀態的唯一標識碼。必要。

要求標頭

使用使用 Microsoft Graph 最佳做法中所列的步驟，要求 API 的標頭。

要求本文

N/A。

回應狀態

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

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

回應承載

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

屬性	必要	描述
id	True	每個回應的唯一標識碼必要。
status	True	值和動作：必要。 notstarted：等候 “Retry-After” 標頭中指定的時間，然後進行另一個呼叫來檢查狀態。 running：等候 “Retry-After” 標頭中指定的時間，然後進行另一個呼叫來檢查狀態。成功：數據已就緒。使用 resourceLocation 中指定的 URI 擷取指令清單承載。 failed：作業永久失敗。重新啟動它。
createdDateTime	True	提出要求的時間。必要。
lastActionDateTime	True	上次變更狀態的時間。必要。
resourceLocation	False	指令清單承載的 URI。選擇性。
error	False	如果作業失敗，則會以 JSON 格式提供錯誤詳細數據。選擇性。包含下列屬性：訊息：錯誤的詳細描述。 code：發生的錯誤類型。

資源位置物件

屬性	描述
id	指令清單的唯一標識碼。
schemaVersion	指令清單架構的版本。
dataFormat	計費數據檔的格式。 compressedJSON：數據格式，其中每個 Blob 都是包含 JSON 行格式數據的壓縮檔。若要從每個 Blob 擷取數據，請將其解壓縮。
createdDateTime	建立指令清單檔的日期和時間。
eTag	指令清單數據的版本。帳單資訊中的變更會產生新的值。
partnerTenantId	合作夥伴租用戶的標識碼。
rootDirectory	檔案的根目錄。
sasToken	SAS（共用存取簽章）令牌，可讓您讀取目錄下的所有檔案。
partitionType	根據 partitionValue 屬性將數據分割成多個 Blob。系統會分割超過支援數目的分割區。根據預設，數據會根據檔案中的明細項目數目進行分割。請勿在程式代碼中設定固定的行專案或檔案大小，因為這些值可能會變更。
blobCount	此合作夥伴租用戶標識碼的檔案總數。
Blob	“blob” 物件的 JSON 陣列，其中包含合作夥伴租使用者標識碼的檔案詳細數據。
blob 物件	物件，其中包含下列詳細數據： name：Blob 的名稱。 partitionValue：包含檔案的分割區。大型分割區會分割成多個檔案，每個檔案都包含相同的「partitionValue」。。
NAME	Blob 的名稱。
partitionValue	包含檔案的分割區。大型分割區會分割成多個檔案，每個檔案都包含相同的「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": "0e195b37-4574-4539-bc42-0e539b9684c0",

        "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 記憶體下載計費發票對帳數據

從指令清單承載 API 回應的「sasToken」和「rootDirectory」屬性取得共用存取簽章（SAS）令牌和 Blob 記憶體位置。 Azure 儲存體 SDK/tool 下載並解壓縮 Blob 檔案。其格式為 JSONLines 。

提示

請查看我們的範例程式代碼，將 Azure Blob 檔案下載並解壓縮到您的本機資料庫。

標準 API 回應狀態

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

代碼	描述
400 – 不正確的要求	要求遺失或包含不正確的數據。請檢查回應本文以取得錯誤詳細數據。
401 - 未經授權	呼叫端未通過驗證，而且您必須先向合作夥伴 API 服務進行驗證，才能進行第一次呼叫。
403 - 禁止	您沒有提出要求的必要授權。
404 – 找不到	所提供的輸入參數無法使用所要求的資源。
410 – 消失	指令清單連結已不再有效或作用中。提交新的要求。
500 – 內部伺服器錯誤	API 或其其中一個相依性目前無法滿足要求。請稍後再試一次。

帳單發票對帳數據屬性

若要比較計費發票對帳 API 針對「完整」或「基本」屬性集所傳回的屬性，請參閱下表。

屬性	完整	基本
PartnerId	是	是
CustomerId	是	是
CustomerName	是	是
CustomerDomainName	是	否
CustomerCountry	是	否
InvoiceNumber	是	是
MpnId	是	否
Tier2MpnId	是	是
OrderId	是	是
OrderDate	是	是
ProductId	是	是
SkuId	是	是
AvailabilityId	是	是
SkuName	是	否
ProductName	是	是
ChargeType	是	是
UnitPrice	是	是
數量	是	否
小計	是	是
TaxTotal	是	是
總數	是	是
貨幣	是	是
PriceAdjustmentDescription	是	是
PublisherName	是	是
PublisherId	是	否
SubscriptionDescription	是	否
SubscriptionId	是	是
ChargeStartDate	是	是
ChargeEndDate	是	是
TermAndBillingCycle	是	是
EffectiveUnitPrice	是	是
UnitType	是	否
AlternateId	是	否
BillableQuantity	是	是
BillingFrequency	是	否
PricingCurrency	是	是
PCToBCExchangeRate	是	是
PCToBCExchangeRateDate	是	否
MeterDescription	是	否
ReservationOrderId	是	是
CreditReasonCode	是	是
SubscriptionStartDate	是	是
SubscriptionEndDate	是	是
ReferenceId	是	是
ProductQualifiers	是	否
PromotionId	是	是
ProductCategory	是	是

範例指令碼

如需使用 API 的指引，請參閱下列連結，其中包含 C# 中的範例程式代碼。

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

Share via

帳單發票對帳 API v2 （GA）

API 概觀

計費發票對帳端點

作業狀態端點

順序圖表

用戶動作順序

步驟 1：提交要求

取得帳單發票對帳明細專案

API 要求

查詢參數

要求本文

要求標頭

API 回應

步驟 2：檢查要求狀態

取得作業狀態

API 要求

要求參數

要求標頭

要求本文

回應狀態

回應承載

資源位置物件

API 要求

API 回應

API 要求

API 回應

步驟 3：從 Azure Blob 記憶體下載計費發票對帳數據

標準 API 回應狀態

帳單發票對帳數據屬性

範例指令碼

意見反應

意見反應

其他資源