帳單發票對帳 API v2 (GA)
適用於: 合作夥伴中心(主權雲端無法使用)
我們的異步 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)。
意見反映
https://aka.ms/ContentUserFeedback。
即將推出:我們會在 2024 年淘汰 GitHub 問題,並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊,請參閱:提交及檢視以下的意見反映: