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

發行項
05/09/2024

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

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

我們已使用代客密鑰和異步要求-回復模式，將新的商務每日評等使用量對帳 API 優化。當您使用這些 API 時，您會收到令牌，可用來存取所有屬性或每日分級使用量對帳數據的子集。

注意

新的 API 不會裝載在合作夥伴中心 API 主機上。相反地，您可以在使用 Microsoft Graph API 匯出合作夥伴帳單數據 - Microsoft Graph v1.0 |Microsoft Learn。若要存取這些 API，請參閱下列詳細數據。

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

注意

如果您一直在使用我們的 Beta 版本，您可能不會注意到正式推出（GA）版本中的重大變更。建議您比較這兩個版本，以了解差異和更新。

重要

新的商務每日評等使用量不包含這些產品的費用：

Azure 保留
Azure 節省方案
Office
Dynamics
Microsoft Power Apps
永久軟體
軟體訂閱
非 Microsoft SaaS 產品

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

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

要求本文

屬性	必要	類型	描述
attributeSet	False	String	針對有限的集合，選擇所有屬性的 [完整] 或 [基本]。預設值為「full」。。（請參閱這裡的屬性清單）。選擇性。
billingPeriod	True	String	使用「目前」或「最後一個」（與 V1 API 中的「上一個」相同）來取得目前或上一個行事曆月份或計費週期的每日分級使用量。必要。
currencyCode	True	String	合作夥伴計費貨幣代碼。必要。

要求標頭

若要要求 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。

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

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

API 要求

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

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

查詢參數

N/A

要求本文

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

要求標頭

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

API 回應

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

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

代碼	描述
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	檢查要求狀態的唯一標識碼。必要。

要求標頭

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

要求本文

N/A。

回應狀態

除了標準 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」。。

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 或其其中一個相依性目前無法滿足要求。請稍後再試一次。

比較 Beta 和 GA 版本

請參閱比較數據表，以瞭解 Beta 和正式推出版本之間的差異。如果您使用 Beta 版本，切換至 GA 版本應該很簡單。

重要資訊	Beta	正式推出
API 主機端點	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
HTTP 方法	POST	POST
每日評等使用量 API 端點未計費	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
未計費每日評等使用量 API 的輸入參數	若要在 API 要求中指定參數，請在要求 URL 的查詢字串中包含這些參數。例如，若要指定 period 和 currencyCode 參數，請將附加 `?period=current&currencyCode=usd` 至要求 URL。	若要提供輸入，請在要求本文中包含 JSON 物件。 JSON 物件應該包含下列屬性： * currencyCode：發票的貨幣碼。例如，美元。 * billingPeriod：發票的計費週期。例如，目前。以下是 JSON 物件的範例，其中包含 currencyCode 和 billingPeriod 屬性：`<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}`
每日評等使用量 API 端點計費	`https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}`	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
計費每日評等使用量 API 的輸入參數	若要在 API 要求中指定參數，請在要求 URL 中包含 invoiceId。此外，您可以在查詢字串中包含選擇性片段參數，以擷取完整的屬性集。例如，若要擷取完整的屬性集，請將附加 `?fragment=full` 至要求URL。	若要提供輸入，請在要求本文中包含 JSON 物件。 JSON 物件應該包含下列屬性： * invoiceId：發票的標識符。例如，G00012345。 * attributeSet：要包含在回應中的屬性集。例如，full。以下是 JSON 物件的範例，其中包含 invoiceId 和 attributeSet 屬性： `{<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}`
指令清單資源	使用個別的 GET /manifests/{id} 方法來擷取指令清單資源。	使用 GET /operations/{Id} 方法，此方法會傳回 resourceLocation 中的相關指令清單資源，而不需要個別呼叫 GET /manifests/{id} 方法。
指令清單架構的變更
	“id”：無法使用	“id”：指令清單資源的唯一標識符。
	“version”： Available	“version”：已重新命名為 “schemaversion”。
	“dataFormat”：可用	“dataFormat”：可用。
	“utcCretedDateTime”： Available	“utcCretedDateTime”：已重新命名為 “createdDateTime”。
	“eTag”：可用	“eTag”：可用。
	“partnerTenantId”： Available	“partnerTenantId”： Available
	“rootFolder”：可用	“rootFolder”：已重新命名為 “rootDirectory”。
	“rootFolderSAS”：可用	“rootFolderSAS”：已重新命名為 “sasToken”。它現在提供令牌，不再包含根目錄路徑。若要存取目錄，請改用「rootDirectory」屬性。
	“partitionType”：可用	“partitionType”：可用。
	“blobCount”：可用	“blobCount”：可用。
	“sizeInBytes”：可用	“sizeInBytes”：無法使用。
	“blobs”：可用	“blobs”：可用。
	“blob 物件”：可用	“blob 物件”：可用。
	“name”： Available	“name”：可用。
	“partitionValue”：可用	“partitionValue”：可用。

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

若要比較每日評分使用量對帳 API 針對「完整」或「基本」屬性集所傳回的屬性，請參閱下列資訊。

屬性	完整	基本
PartnerId	是	是
PartnerName	是	是
CustomerId	是	是
CustomerName	是	Yes
CustomerDomainName	是	否
CustomerCountry	是	否
MpnId	是	否
Tier2MpnId	是	否
InvoiceNumber	是	是
ProductId	是	是
SkuId	是	是
AvailabilityId	是	否
SkuName	是	是
ProductName	是	否
PublisherName	是	是
PublisherId	是	否
SubscriptionDescription	是	否
SubscriptionId	是	是
ChargeStartDate	是	是
ChargeEndDate	是	是
UsageDate	是	是
MeterType	是	否
計量類別目錄	是	否
MeterId	是	否
MeterSubCategory	是	否
MeterName	是	否
MeterRegion	是	否
單位	是	是
資源位置	是	否
ConsumedService	是	否
ResourceGroup	是	否
ResourceURI	是	是
ChargeType	是	是
UnitPrice	是	是
數量	是	是
UnitType	是	否
BillingPreTaxTotal	是	是
BillingCurrency	是	是
PricingPreTaxTotal	是	是
PricingCurrency	是	是
ServiceInfo1	是	否
ServiceInfo2	是	否
標籤	是	否
AdditionalInfo	是	否
EffectiveUnitPrice	是	是
PCToBCExchangeRate	是	是
EntitlementId	是	是
EntitlementDescription	是	否
PartnerEarnedCreditPercentage	是	否
CreditPercentage	是	是
CreditType	是	是
BenefitOrderID	是	是
BenefitID	是	否
BenefitType	是	是

重要

從 v1 移至 API v2 時，請記下這些變更。

每個屬性的名稱都會以大寫開頭。
unitOfMeasure 現在是 Unit。 屬性的意義和值相同。
resellerMpnId 現在是 Tier2MpnId。屬性的意義和值相同。
rateOfPartnerEarnedCredit 的名稱和值已變更為 PartnerEarnedCreditPercentage。 屬性的新名稱和值會反映百分比，而不是分數。例如，0.15 現在是15。
rateOfCredit 現在是 CreditPercentage。 屬性的意義和值已變更。例如，1.00 現在是 100。

範例指令碼

若要深入瞭解，請參閱合作夥伴中心 API 範例：取得帳單對帳數據。

Share via

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

API 概觀

使用明細專案端點

作業狀態端點

順序圖表

用戶動作順序

步驟 1：提交要求

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

API 要求

要求本文

要求標頭

API 回應

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

API 要求

要求本文

要求標頭

API 回應

步驟 2：檢查要求狀態

取得作業狀態

API 要求

要求參數

要求標頭

要求本文

回應狀態

回應承載

資源位置物件

API 要求

API 回應

API 要求

API 回應

步驟 3：從 Azure Blob 記憶體下載每日評等使用量對帳明細專案

標準 API 回應狀態

比較 Beta 和 GA 版本

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

範例指令碼

意見反應

意見反應

其他資源