Ottenere le voci di utilizzo commerciale non fatturate

Articolo
02/04/2025

Nota

date e scenari di migrazione chiave

La strategia di transizione della versione dell'API è progettata per garantire una migrazione uniforme dall'API v1 all'API v2, con particolare attenzione alla gestione delle funzionalità e dell'integrità dei dati. Ecco una guida che consente di selezionare la versione dell'API appropriata per le proprie esigenze:

scenario A: Periodi di fatturazione correnti o precedenti (prima del 21 aprile 2025):

Continuare a usare questa API fino al 21 aprile 2025, a meno che non sia già stata eseguita la transizione all'API v2 GA.

scenario B: periodi di fatturazione correnti o precedenti (dopo il 21 aprile 2025):

Passare all'API v2 ga per tutto il recupero dei dati del periodo di fatturazione futuro.

La transizione dall'API v1 all'API v2 implica una pianificazione dettagliata e un'esecuzione precisa. Per garantire una transizione senza problemi alla nuova API, visitare: API di riconciliazione dell'utilizzo giornaliero valutato, fatturato e non fatturato v2 (GA).

Apprezziamo la tua attenzione e ci impegniamo a supportare il tuo successo continuo con le nostre API di fatturazione.

Come ottenere una raccolta di dettagli della riga di utilizzo commerciale non fatturati.

È possibile utilizzare i metodi seguenti per ottenere una raccolta di dettagli non fatturati voci di utilizzo commerciale (note anche come voci di utilizzo aperte) a livello di codice.

Importante

I dati di utilizzo valutati giornalieri non includono gli addebiti per questi prodotti:

Prenotazione di Azure
Piano di risparmio di Azure
Office
Dynamics
Microsoft Power Apps
Software perpetuo
Sottoscrizione software
Prodotto SaaS non Microsoft o marketplace

Nota

È possibile accedere alle voci di utilizzo giornaliere non fatturate tramite l'API o il portale del Centro per i partner. Per garantire l'accuratezza dei dati, potrebbero essere necessarie fino a 24 ore prima che siano disponibili. A seconda della posizione e quando i contatori segnalano l'utilizzo, potrebbero verificarsi ulteriori ritardi.

Prima di tutto viene assegnata la priorità al recapito in base al tempo dei dati di utilizzo fatturati giornalieri. In alcuni casi, i non fatturati più recenti dati di utilizzo valutati giornalieri potrebbero non essere visualizzati fino a quando non sono disponibili i dati fatturati del mese precedente. Dopo aver ricevuto i dati fatturati, è possibile accedere a tutti i dati di utilizzo non fatturati aggiornati dall'inizio del mese.

punti chiave:

Attendere fino a 24 ore per la disponibilità dei dati.
Potrebbero verificarsi ulteriori ritardi a seconda della posizione e dei tempi di segnalazione del contatore.
I dati di utilizzo giornalieri fatturati vengono classificati in ordine di priorità rispetto ai dati non fatturati.

La comprensione e la pazienza sono apprezzate come ci sforziamo di fornire le informazioni più accurate e tempestive possibili.

Prerequisiti

Credenziali descritte in Autenticazione del Centro per i partner. Questo scenario supporta l'autenticazione con le credenziali app autonome e App+Utente.

C#

Per ottenere le voci per la fattura specificata:

Chiamare il metodo ById per ottenere un'interfaccia alle operazioni della fattura per la fattura specificata.
Chiamare il metodo Get o GetAsync per recuperare l'oggetto fattura.

L'oggetto fattura contiene tutte le informazioni per la fattura specificata. Il provider identifica l'origine delle informazioni dettagliate non fatturate, ad esempio OneTime. InvoiceLineItemType specifica il tipo , ad esempio UsageLineItem.

Il codice di esempio seguente usa un ciclo foreach per elaborare l'insieme InvoiceLineItems . Viene recuperata una raccolta separata di elementi riga per ogni InvoiceLineItemType.

Per ottenere una raccolta di voci che corrispondono a un'istanza invoiceDetail :

Passare l'oggetto BillingProvider e InvoiceLineItemType dell'istanza al metodo By.
Chiamare il metodo Get o GetAsync per recuperare gli elementi di riga associati.
Creare un enumeratore per attraversare la raccolta, come illustrato nell'esempio seguente.

// IAggregatePartner partnerOperations;
// 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("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Get();

var fetchNext = true;

ConsoleKeyInfo keyInfo;

var itemNumber = 1;
while (fetchNext)
{
    Console.Out.WriteLine("\tLine 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("unbilled").By("onetime", "usagelineitems", curencyCode, period, pageMaxSizeReconLineItems).Seek(seekBasedResourceCollection.ContinuationToken, SeekOperation.Next);
        }
    }
}

Per un esempio simile, vedere:

Esempio: App di test della console
Progetto: Esempi di SDK del Centro per i partner
Classe: GetUnBilledConsumptionReconLineItemsPaging.cs

Richiesta REST

Sintassi della richiesta

È possibile usare le sintassi seguenti per la richiesta REST, a seconda del caso d'uso. Per altre informazioni, vedere le descrizioni per ogni sintassi.

metodo	URI della richiesta	Descrizione del caso d'uso della sintassi
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period} HTTP/1.1	Utilizzare questa sintassi per restituire un elenco completo di ogni voce per la fattura specificata.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size} HTTP/1.1	Usare questa sintassi per le fatture di grandi dimensioni. Utilizzare questa sintassi con una dimensione specificata e un offset basato su 0 per restituire un elenco di voci di paging.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size}&seekOperation=Next	Usare questa sintassi per ottenere la pagina successiva degli elementi della riga di riconciliazione usando `seekOperation = "Next"`.

Parametri URI

Usare gli URI e i parametri di query seguenti durante la creazione della richiesta.

Nome	Digita	Obbligatorio	Descrizione
provider	string	Sì	Provider: "OneTime".
invoice-line-item-type	string	Sì	Tipo di dettaglio fattura: "UsageLineItems", "UsageLineItems".
currencyCode	string	Sì	Codice di valuta per gli elementi di riga non fatturati.
period	string	Sì	Periodo di riconciliazione non fatturata (ad esempio: corrente, precedente). Si supponga di dover eseguire una query sui dati di utilizzo non fatturati del ciclo di fatturazione (01/01/2020 - 31/01/2020) nel mese di gennaio, scegliere periodo come "Corrente", altrimenti "Indietro".
size	number	No	Numero massimo di elementi da restituire. La dimensione predefinita è 2000.
seekOperation	string	No	Impostare `seekOperation=Next` per ottenere la pagina successiva delle voci di riconciliazione.

Intestazioni delle richieste

Per altre informazioni, vedi Intestazioni REST del Centro per i partner.

Testo della richiesta

Nessuno.

Risposta REST

In caso di esito positivo, la risposta contiene la raccolta di dettagli dell'elemento di riga.

Per l'elemento riga ChargeType, il valore Purchase viene mappato a Nuovo e il valore Rimborso viene mappato a Annulla.

Codici di errore e di esito della risposta

Ogni risposta viene fornita con un codice di stato HTTP che indica l'esito positivo o negativo e altre informazioni di debug. Usare uno strumento di traccia di rete per leggere questo codice, il tipo di errore e altri parametri. Per l'elenco completo, vedi Codici di errore REST del Centro per i partner.

Esempi di richiesta-risposta

Esempio di richiesta-risposta 1

I dettagli seguenti si applicano a questo esempio:

Provider: OneTime
InvoiceLineItemType: UsageLineItems
Periodo: Precedente

Esempio di richiesta 1

GET https://api.partnercenter.microsoft.com/v1//invoices/unbilled/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

Importante

A partire da giugno 2023, la versione più recente di .NET SDK del Centro per i partner 3.4.0 è ora archiviata. È possibile scaricare la versione dell'SDK da GitHub, insieme a un file leggimi che contiene informazioni utili.

I partner sono invitati a continuare a usare le API REST del Centro per i partner.

Esempio di risposta 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": "00083575-bbd0-54de-b2ad-0f5b0e927d71",
            "partnerName": "MTBC",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "VM-Series Next-Generation Firewall (Bundle 2 PAYG)",
            "productName": "VM-Series Next Generation Firewall",
            "publisherName": "Test Alto Networks, Inc.",
            "publisherId": "",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Pay-As-You-Go",
            "chargeStartDate": "2019-01-01T00:00:00Z",
            "chargeEndDate": "2019-02-01T00:00:00Z",
            "usageDate": "2019-01-01T00:00:00Z",
            "meterType": "1 Compute Hour - 4core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "4core",
            "meterSubCategory": "VM-Series Next Generation Firewall",
            "meterName": "VM-Series Next Generation Firewall - VM-Series Next-Generation Firewall (Bundle 2 PAYG) - 4 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "ECH-PAN-RG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ECH-PAN-RG/providers/Microsoft.Compute/virtualMachines/echpanfw",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_D3_v2\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "",
            "unitPrice": 1.2799888920023,
            "quantity": 24.0,
            "unitType": "",
            "billingPreTaxTotal": 30.7197334080551,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 30.7197334080551,
            "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": "00083575-bbd0-54de-b2ad-0f5b0e927d71",
            "partnerName": "MTBC",
            "customerId": "",
            "customerName": "",
            "customerDomainName": "",
            "invoiceNumber": "",
            "productId": "",
            "skuId": "",
            "availabilityId": "",
            "skuName": "VM-Series Next-Generation Firewall (Bundle 2 PAYG)",
            "productName": "VM-Series Next Generation Firewall",
            "publisherName": "Test Alto Networks, Inc.",
            "publisherId": "",
            "subscriptionId": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
            "subscriptionDescription": "Pay-As-You-Go",
            "chargeStartDate": "2019-01-01T00:00:00Z",
            "chargeEndDate": "2019-02-01T00:00:00Z",
            "usageDate": "2019-01-02T00:00:00Z",
            "meterType": "1 Compute Hour - 4core",
            "meterCategory": "Virtual Machine Licenses",
            "meterId": "4core",
            "meterSubCategory": "VM-Series Next Generation Firewall",
            "meterName": "VM-Series Next Generation Firewall - VM-Series Next-Generation Firewall (Bundle 2 PAYG) - 4 Core Hours",
            "meterRegion": "",
            "unitOfMeasure": "1 Hour",
            "resourceLocation": "EASTUS",
            "consumedService": "Microsoft.Compute",
            "resourceGroup": "ECH-PAN-RG",
            "resourceUri": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/ECH-PAN-RG/providers/Microsoft.Compute/virtualMachines/echpanfw",
            "tags": "",
            "additionalInfo": "{  \"ImageType\": null,  \"ServiceType\": \"Standard_D3_v2\",  \"VMName\": null,  \"VMProperties\": null,  \"UsageType\": \"ComputeHR_SW\"}",
            "serviceInfo1": "",
            "serviceInfo2": "",
            "customerCountry": "",
            "mpnId": "1234567",
            "resellerMpnId": "",
            "chargeType": "",
            "unitPrice": 1.2799888920023,
            "quantity": 24.0,
            "unitType": "",
            "billingPreTaxTotal": 30.7197334080551,
            "billingCurrency": "USD",
            "pricingPreTaxTotal": 30.7197334080551,
            "pricingCurrency": "USD",
            "entitlementId": "31cdf47f-b249-4edd-9319-637862d12345",
            "entitlementDescription": "Partner Subscription",
            "pcToBCExchangeRate": 1,
            "pcToBCExchangeRateDate": "2019-08-01T00:00:00Z",
            "effectiveUnitPrice": 0,
            "rateOfPartnerEarnedCredit": 0,
            "rateOfCredit": 1,
            "creditType": "Azure Credit Applied",
            "invoiceLineItemTypce": "usage_line_items",
            "billingProvider": "marketplace",
        "benefitOrderId": "",
            "benefitId": "",
            "benefitType": "Charge",
            "attributes": {
                "objectType": "DailyRatedUsageLineItem"
            }
        }
    ],
    "links": {
        "self": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000",
            "method": "GET",
            "headers": []
        },
        "next": {
            "uri": "/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems&currencycode=usd&period=previous&size=2000&seekOperation=Next",
            "method": "GET",
            "headers": [
                {
                    "key": "MS-ContinuationToken",
                    "value": "AQAAAA=="
                }
            ]
        }
    },
    "attributes": {
        "objectType": "Collection"
    }
}

Esempio di richiesta-risposta 2