Pobieranie elementów wiersza komercyjnego użycia rozliczonego na fakturze

Artykuł
10/04/2024

Uwaga

Po 21 stycznia 2025 r. możesz nadal korzystać z tego interfejsu API, ale nie dla każdego okresu rozliczeniowego. Poniżej przedstawiono sposób wybierania odpowiedniej wersji na podstawie Twoich potrzeb:

Cel: Pobierz dzienne elementy wierszy użycia oceny dla okresów rozliczeniowych od września 2022 r. do grudnia 2024 r.
Akcja: Użyj tego interfejsu API do 21 stycznia 2025 r., chyba że został już przełączony do interfejsu API w wersji 2 ( ogólna dostępność).
Cel: Pobierz dzienne elementy wierszy użycia ocenianego dla okresów rozliczeniowych przed wrześniem 2022 r.
Akcja: użyj wyłącznie tego interfejsu API.
Cel: Pobierz dzienne elementy wierszy użycia ocenianego dla okresów rozliczeniowych od września 2022 r., ale dopiero po 21 stycznia 2025 r.
Akcja: użyj tylko interfejsu API w wersji 2 (ogólna dostępność).

Aby bezproblemowo przejść do nowych interfejsów API, postępuj zgodnie z tym linkiem: Rozliczane i nienaliczone codziennie interfejs API uzgodnień użycia w wersji 2 (GA).

Dziękujemy za twoją uwagę i czekamy na twój ciągły sukces z naszymi interfejsami API rozliczeń.

Poniższe metody umożliwiają pobranie kolekcji szczegółów dotyczących elementów wiersza faktury z użyciem komercyjnych (nazywanych również zamkniętymi elementami wierszy dziennego użycia) dla określonej faktury.

Ważne

Dane dziennego użycia nie obejmują opłat za te produkty:

Rezerwacja platformy Azure
Plan oszczędnościowy Azure
Office
Dynamics
Microsoft Power Apps
Oprogramowanie bezterminowe
Subskrypcja oprogramowania
Produkt SaaS firmy innej niż Microsoft lub Marketplace

Wymagania wstępne

Poświadczenia zgodnie z opisem w temacie Uwierzytelnianie w Centrum partnerskim. Ten scenariusz obsługuje uwierzytelnianie zarówno przy użyciu autonomicznych poświadczeń aplikacji, jak i aplikacji i użytkownika.
Identyfikator faktury w celu pobrania elementów wiersza.

C#

Aby pobrać elementy wiersza komercyjnego dla określonej faktury, należy pobrać obiekt faktury:

Wywołaj metodę ById , aby pobrać interfejs do operacji na fakturze dla określonej faktury.
Wywołaj metodę Get lub GetAsync , aby pobrać obiekt faktury. Obiekt faktury zawiera wszystkie informacje dotyczące określonej faktury.

Dostawca identyfikuje źródło rozliczanych informacji szczegółowych (na przykład jednorazowo). Parametr InvoiceLineItemType określa typ (na przykład UsageLineItem).

Poniższy przykładowy kod używa pętli foreach do przetwarzania kolekcji elementów wiersza. Dla każdego elementu InvoiceLineItemType jest pobierana oddzielna kolekcja elementów wiersza.

Aby uzyskać kolekcję elementów wiersza odpowiadających wystąpieniu InvoiceDetail :

Przekaż element BillingProvider i InvoiceLineItemType wystąpienia do metody By.
Wywołaj metodę Get lub GetAsync , aby pobrać skojarzone elementy wiersza.
Utwórz moduł wyliczający, aby przejść przez kolekcję, jak pokazano w poniższym przykładzie.

// 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);
        }
    }
}

Zobacz przykład:

Przykład: aplikacja testowa konsoli
Projekt: Przykłady zestawu SDK Centrum partnerskiego
Klasa: GetBilledConsumptionReconLineItemsPaging.cs

Żądanie REST

Składnia żądania

Użyj pierwszej składni, aby zwrócić pełną listę każdego elementu wiersza dla danej faktury. W przypadku dużych faktur użyj drugiej składni z określonym rozmiarem i przesunięciem na podstawie 0 w celu zwrócenia stronicowanej listy elementów wiersza. Użyj trzeciej składni, aby uzyskać następną stronę elementów wierszy ponownego tworzenia przy użyciu polecenia seekOperation = "Next".

Method	Identyfikator URI żądania
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size} HTTP/1.1
GET	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size}&seekOperation=Next

Parametry identyfikatora URI

Podczas tworzenia żądania użyj następującego identyfikatora URI i parametrów zapytania.

Nazwisko	Type	Wymagania	opis
identyfikator faktury	string	Tak	Ciąg identyfikujący fakturę.
dostawca	string	Tak	Dostawca: "OneTime".
typ elementu faktury	string	Tak	Typ szczegółów faktury: "UsageLineItems".
currencyCode	string	Tak	Kod waluty dla rozliczanych elementów wiersza.
okres	string	Tak	Okres opłat za rozliczenie. przykład: bieżący, poprzedni.
size	numer	Nie.	Maksymalna liczba elementów do zwrócenia. Domyślny rozmiar to 2000
seekOperation	string	Nie	Ustaw wartość seekOperation=Next, aby pobrać następną stronę elementów wiersza ponownego tworzenia.

Nagłówki żądań

Aby uzyskać więcej informacji, zobacz Nagłówki REST Centrum partnerskiego.

Treść żądania

Brak.

Odpowiedź REST

W przypadku powodzenia odpowiedź zawiera kolekcję szczegółów elementu wiersza.

W przypadku elementu wiersza ChargeType wartość Zakup jest mapowana na nowy. Wartość Zwrot jest mapowana na Anuluj.

Kody powodzenia i błędów odpowiedzi

Każda odpowiedź zawiera kod stanu HTTP, który wskazuje powodzenie lub niepowodzenie i inne informacje o debugowaniu. Użyj narzędzia do śledzenia sieci, aby odczytać ten kod, typ błędu i inne parametry. Aby uzyskać pełną listę, zobacz Kody błędów REST Centrum partnerskiego.

Przykłady rest

Przykład odpowiedzi na żądanie 1

Szczegóły tego przykładowego żądania REST i odpowiedzi są następujące:

Dostawca: OneTime
InvoiceLineItemType: UsageLineItems
Okres: poprzedni

Przykład żądania 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

Ważne

Od czerwca 2023 r. najnowsza wersja zestawu .NET SDK Centrum partnerskiego 3.4.0 jest teraz archiwizowana. Możesz pobrać wersję zestawu SDK z usługi GitHub wraz z plikiem readme zawierającym przydatne informacje.

Zachęcamy partnerów do dalszego korzystania z interfejsów API REST Centrum partnerskiego.

Przykład odpowiedzi 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"
    }
}

Przykład odpowiedzi na żądanie 2