取得已開立發票的商業消耗明細項目

2025-04-30

注意

主要移轉日期和案例

API 版本轉換策略的設計目的是確保從 API v1 順利移轉至 API v2，並著重於維護功能和數據完整性。以下指南可協助您針對需求選取適當的 API 版本：

案例 A：歷程記錄數據（2022 年 9 月計費期間之前）：

僅使用此 API 來滿足您的所有需求。

案例 B：最近的計費期間（2022 年 9 月 - 2025 年 3 月）：

除非您已轉換至 API v2 GA，否則請繼續使用此 API，直到 2025 年 4 月 21 日為止。

案例 C：2025 年 3 月之後的未來計費期間（2025 年 4 月 21 日之後）：

所有未來的計費期間數據擷取請切換至 API v2 GA。

從 API v1 轉換至 API v2 牽涉到詳細的規劃和精確執行。若要確保順利過渡到新的 API，請造訪：每日計費和未計費使用量結算 API v2（GA）。

感謝您的注意，並致力於透過我們的計費 API 支援您持續的成功。

案例 D：舊版商務數據（所有計費期間）：完全針對您的所有需求使用此 API。

您可以使用下列方法來取得指定發票的商業使用發票列項的詳細數據集合（也稱為已關閉的每日結算使用量明細項）。

重要

每日評等使用量數據不包含這些產品的費用：

Azure 預訂
Azure 節省方案
辦公室
動態
Microsoft Power Apps
永久軟體
軟體訂閱
非Microsoft或 Marketplace SaaS 產品

必要條件

憑證，如合作夥伴中心身份驗證中所描述。此案例支援使用獨立應用程式和 App+使用者認證進行驗證。
要用來取得明細項目的發票編號。

C#

若要取得指定發票的商業明細項目，您必須獲取發票物件：

呼叫 ById 方法，以取得指定發票的發票作業介面。
使用 Get 或 GetAsync 方法來擷取發票物件。 invoice 物件包含指定發票的所有資訊。

提供者會識別計費詳細資訊的來源（例如一次）。 InvoiceLineItemType 會指定類型（例如 UsageLineItem）。

下列範例程式代碼會使用 foreach 循環來處理行專案集合。系統會為每個 InvoiceLineItemType 取得一個單獨的明細項目集合。

若要取得對應至 InvoiceDetail 實例的項目集合：

將實例的 BillingProvider 和 InvoiceLineItemType 傳遞至 By 方法。
呼叫 Get 或 GetAsync 方法來擷取相關聯的明細項目。
建立一個列舉器以遍歷集合，如範例所示。

// IAggregatePartner partnerOperations;
// string invoiceId;
// string curencyCode;
// string period;
// int pageMaxSizeReconLineItems = 2000;

// all the operations executed on this partner operation instance will share the same correlation Id but will differ in request Id
IPartner scopedPartnerOperations = partnerOperations.With(RequestContextFactory.Instance.Create(Guid.NewGuid()));

var seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById(invoiceId).By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine line items count: " + seekBasedResourceCollection.Items.Count());

    seekBasedResourceCollection.Items.ToList().ForEach(item =>
    {
        // Instance of type DailyRatedUsageLineItem
        if (item is DailyRatedUsageLineItem)
        {
            Type t = typeof(DailyRatedUsageLineItem);
            PropertyInfo[] properties = t.GetProperties();

            foreach (PropertyInfo property in properties)
            {
                // Insert code here to work with the line item properties
            }
        }
        itemNumber++;
    });

    Console.Out.WriteLine("\tPress any key to fetch next data. Press the Escape (Esc) key to quit: \n");
    keyInfo = Console.ReadKey();

    if (keyInfo.Key == ConsoleKey.Escape)
    {
        break;
    }

    fetchNext = !string.IsNullOrWhiteSpace(seekBasedResourceCollection.ContinuationToken);

    if (fetchNext)
    {
        if (seekBasedResourceCollection.Links.Next.Headers != null && seekBasedResourceCollection.Links.Next.Headers.Any())
        {
            seekBasedResourceCollection = scopedPartnerOperations.Invoices.ById(invoiceId).By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

請參閱範例：

範例：控制台測試應用程式
專案： 合作夥伴中心 SDK 範例
類別：GetBilledConsumptionReconLineItemsPaging.cs

REST 要求

要求語法

使用第一個語法可傳回所提供發票中每個項目的完整清單。對於大型發票，請使用第二種語法格式，搭配指定的大小和從0開始的偏移量，以傳回分頁的明細項目清單。使用第三種語法來取得下一頁的對帳明細項目，使用seekOperation = "Next"即可。

方法	要求 URI
獲取	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode} HTTP/1.1
獲取	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size} HTTP/1.1
獲取	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size}&seekOperation=Next

URI 參數

建立要求時，請使用下列 URI 和查詢參數。

名稱	類型	必要	描述
發票編號	字串	是的	識別發票的字串。
提供者	字串	是的	提供者：「OneTime」。
發票項目類型	字串	是的	發票詳細數據的類型：「UsageLineItems」。
貨幣代碼	字串	是的	計費明細項目的貨幣代碼。
句號	字串	是的	計費對帳的期間。範例：目前、前一個。
大小	數字	不	要傳回的項目數上限。默認大小為 2000
搜尋操作	字串	不	將 seekOperation 設為 Next 以取得下一頁的對帳項目。

請求標頭

如需詳細資訊，請參閱合作夥伴中心 REST 標頭。

請求正文

無。

REST 回應

如果成功，回應會包含項目的細節集合。

對於明細專案 ChargeType，購買值會對應至 New。退款的值會對應至取消。

回應成功和錯誤碼

每個回應都有一個 HTTP 狀態代碼，指出成功或失敗和其他偵錯資訊。使用網路追蹤工具來讀取此程式代碼、錯誤類型等等參數。如需完整清單，請參閱合作夥伴中心 REST 錯誤碼。

REST 範例

要求回應範例 1

此範例 REST 要求和回應的詳細資料如下：

提供者： OneTime
InvoiceLineItemType： UsageLineItems
期間：上一個

要求範例 1

GET https://api.partnercenter.microsoft.com/v1/invoices/T000001234/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000 HTTP/1.1
Authorization: Bearer <token>
Accept: application/json
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
X-Locale: en-US
MS-PartnerCenter-Application: Partner Center .NET SDK Samples
Host: api.partnercenter.microsoft.com

重要

自 2023 年 6 月起，最新的合作夥伴中心 .NET SDK 3.4.0 版現已封存。您可以從 GitHub 下載 SDK 發行版本，還有包含實用資訊的自述檔。

鼓勵合作夥伴繼續使用合作夥伴中心 REST API。

回應範例 1

HTTP/1.1 200 OK
Content-Length: 2484
Content-Type: application/json; charset=utf-8
MS-CorrelationId: aaaa0000-bb11-2222-33cc-444444dddddd
MS-RequestId: 1234ecb8-37af-45f4-a1a1-358de3ca2b9e
MS-CV: bpqyomePDUqrSSYC.0
MS-ServerId: 202010406
Date: Wed, 20 Feb 2019 19:59:27 GMT

{
    "totalCount": 2,
    "items": [
        {
            "partnerId": "2b8940db-5089-539c-e757-520ed1d1bc88",
            "partnerName": "",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "T000001234",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "Test Test on Windows 2012 R2 (WebHost)",
            "productName": "Test Test on Windows",
            "publisherName": "Test",
            "publisherId": "28503520",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Subscription 10",
            "chargeStartDate": "2018-11-01T00:00:00Z",
            "chargeEndDate": "2018-12-01T00:00:00Z",
            "usageDate": "2018-11-13T00:00:00Z",
            "meterType": "1 Compute Hour - 1core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "1core",
            "meterSubCategory": "Test Test on Windows",
            "meterName": "Test Test on Windows - Test Test on Windows 2012 R2 (WebHost) - 1 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS2",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "TestWINRG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/TestWINRG/providers/Microsoft.Compute/virtualMachines/testWinTest",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_B1s\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "new",
            "unitPrice": 0.0209496384791679,
            "quantity": 23.200004,
            "unitType": "1 Hour",
            "billingPreTaxTotal": 0.486031696515249,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 0.486031696515249,
            "pricingCurrency": "USD",
            "entitlementId": "3f47bcf1-965d-40a1-a2bc-3d5db3653250",
	    "entitlementDescription": "Partner Subscription",
	    "pcToBCExchangeRate": 1,
	    "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
	    "effectiveUnitPrice": 0,
	    "rateOfPartnerEarnedCredit": 0,
	    "rateOfCredit": 0,
	    "creditType": "Credit Not Applied",
	    "invoiceLineItemType": "usage_line_items",
            "billingProvider": "marketplace",
	    "benefitOrderId": "5ea053d6-4a0d-46ef-bc82-15065b475d01",
	    "benefitId": "28ddab06-2c5b-479e-88bb-7b7bfda4e7fd",
	    "benefitType": "SavingsPlan",
            "attributes": {
                "objectType": "DailyRatedUsageLineItem"
            }
        },
        {
            "partnerId": "2b8940db-5089-539c-e757-520ed1d1bc88",
            "partnerName": "",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "T000001234",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "Test Test on Ubuntu 16.04 (WebHost)",
            "productName": "Test Test on Linux",
            "publisherName": "Test",
            "publisherId": "28503520",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Subscription 10",
            "chargeStartDate": "2018-11-01T00:00:00Z",
            "chargeEndDate": "2018-12-01T00:00:00Z",
            "usageDate": "2018-11-13T00:00:00Z",
            "meterType": "1 Compute Hour - 1core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "1core",
            "meterSubCategory": "Test Test on Linux",
            "meterName": "Test Test on Linux - Test Test on Ubuntu 16.04 (WebHost) - 1 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "TESTRG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/TestRG/providers/Microsoft.Compute/virtualMachines/testUbuntuTest",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_B1s\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "new",
            "unitPrice": 0.0209951014286867,
            "quantity": 23.350007,
            "unitType": "1 Hour",
            "billingPreTaxTotal": 0.490235765325545,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 0.490235765325545,
            "pricingCurrency": "USD",
            "entitlementId": "66bada28-271e-4b7a-aaf5-c0ead6312345",
            "entitlementDescription": "Partner Subscription",
            "pcToBCExchangeRate": 1,
            "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
            "effectiveUnitPrice": 0.1999968000511991808131,
            "rateOfPartnerEarnedCredit": 0,
            "rateOfCredit": 1,
            "creditType": "Azure Credit Applied",
            "invoiceLineItemType": "usage_line_items",
            "billingProvider": "marketplace",
	    "benefitOrderId": "",
            "benefitId": "",
            "benefitType": "Charge",
            "attributes": {
                "objectType": "DailyRatedUsageLineItem"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/invoices/T000001234/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000",
            "method": "GET",
            "headers": []
        },
        "next": {
            "uri": "/invoices/T000001234/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000&seekOperation=Next",
            "method": "GET",
            "headers": [
                {
                    "key": "MS-ContinuationToken",
                    "value": "AQAAAA=="
                }
            ]
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

要求回應範例 2