Obter os itens de linha de consumo comercial cobrados pela fatura

Observação

principais datas e cenários de migração

A estratégia de transição de versão da API foi projetada para garantir uma migração suave da API v1 para a API v2, com foco na manutenção da funcionalidade e da integridade dos dados. Aqui está um guia para ajudá-lo a selecionar a versão da API apropriada para suas necessidades:

Cenário A: Dados históricos (antes do período de cobrança de setembro de 2022):

Use exclusivamente esta API para todas as suas necessidades.

Cenário B: Períodos de cobrança recentes (setembro de 2022 a março de 2025):

continuar usando essa API até 21 de abril de 2025, a menos que você já tenha feito a transição para a API v2 GA.

Cenário C: Períodos futuros de cobrança após março de 2025 (após 21 de abril de 2025):

Mudar para a API v2 GA para a recuperação de dados de todos os períodos de cobrança futuros.

A transição da API v1 para a API v2 envolve planejamento detalhado e execução precisa. Para garantir uma transição adequada para a nova API, acesse: API de reconciliação de uso diário com tarifa faturada e não faturada v2 (GA).

Agradecemos sua atenção e estamos comprometidos em apoiar seu sucesso contínuo com nossas APIs de cobrança.

Cenário D: dados de Comércio Herdado (todos os períodos de cobrança): use essa API exclusivamente para todas as suas necessidades.

Você pode usar os seguintes métodos para obter uma coleção de detalhes para itens de linha de fatura de consumo comercial (também conhecidos como itens de linha de uso diário faturado fechado) para uma fatura especificada.

Importante

Os dados de uso diário não incluem as cobranças destes produtos:

Reserva do Azure
Plano de economia do Azure
Office
Dinâmica
Aplicativos do Microsoft Power
Software com licença perpétua
Assinatura de software
Produto SaaS não Microsoft ou Microsoft Marketplace

Pré-requisitos

Credenciais, conforme descrito em Autenticação do Partner Center. Esse cenário dá suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.
A ID da Fatura para obter os itens de linha.

C#

Para obter os itens de linha comercial da fatura especificada, você precisa recuperar o objeto da fatura:

Chame o método ById para obter uma interface para operações de fatura para a fatura especificada.
Chame o método Get ou GetAsync para recuperar o objeto da fatura. O objeto de fatura contém todas as informações da fatura especificada.

O Provedor identifica a origem das informações detalhadas faturadas (por exemplo, onetime). O InvoiceLineItemType especifica o tipo (por exemplo, UsageLineItem).

O código de exemplo a seguir usa um loop foreach para processar a coleção de itens da linha. Uma coleção separada de itens de linha é recuperada para cada InvoiceLineItemType.

Para obter uma coleção de itens de linha que correspondem a uma instância de InvoiceDetail:

Passe o BillingProvider e o InvoiceLineItemType da instância para o método By.
Chame o método Get ou GetAsync para recuperar os itens de linha associados.
Crie um enumerador para percorrer a coleção, conforme mostrado no exemplo a seguir.

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

Veja um exemplo:

Exemplo: aplicativo de teste de console
Projeto: Exemplos de SDK do Partner Center
Classe: GetBilledConsumptionReconLineItemsPaging.cs

Solicitação REST

Sintaxe da solicitação

Use a primeira sintaxe para retornar uma lista completa de todos os itens de linha da fatura especificada. Para faturas grandes, use a segunda sintaxe com um tamanho especificado e um deslocamento baseado em 0 para retornar uma lista paginada de itens de linha. Use a terceira sintaxe para obter a próxima página de itens de linha de reconhecimento usando seekOperation = "Next".

Método	URI de solicitação
OBTER	[https://blogs.technet.microsoft.com/askperf/2008/11/18/disabling-unnecessary-services-a-word-to-the-wise/]() {baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode} HTTP/1.1
OBTER	{baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size={size} HTTP/1.1
OBTER	[https://blogs.technet.microsoft.com/askperf/2008/11/18/disabling-unnecessary-services-a-word-to-the-wise/]() {baseURL}/v1/invoices/{invoice-id}/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&size={size}&seekOperation=Next

Parâmetros do URI

Use o URI e os parâmetros de consulta a seguir ao criar a solicitação.

Nome	Tipo	Obrigatória	Descrição
ID da fatura	cadeia	Sim	Uma cadeia de caracteres que identifica a fatura.
fornecedor	cadeia	Sim	O provedor: "OneTime".
tipo de item de linha de fatura	cadeia	Sim	O tipo de detalhe da fatura: “UsageLineItems”.
código de moeda	cadeia	Sim	O código de moeda para os itens de linha faturados.
período	cadeia	Sim	O período para o reconhecimento faturado. exemplo: current, previous.
tamanho	número	Não	O número máximo de itens a serem devolvidos. O tamanho padrão é 2000
seekOperation	cadeia	Não	Defina seekOperation=Next para obter a próxima página de itens de linha de reconhecimento.

Cabeçalhos da solicitação

Para mais informações, consulte os cabeçalhos REST do Partner Center.

Corpo da solicitação

Nenhum.

Resposta REST

Se bem-sucedida, a resposta contém a coleção de detalhes do item de linha.

Para o item ChargeType, o valor Purchase é mapeado para New. O valor Reembolso é mapeado para Cancelar.

Códigos de êxito e de erro de resposta

Cada resposta vem com um código de status HTTP que indica êxito ou falha e outras informações de depuração. Use uma ferramenta de rastreamento de rede para ler esse código, tipo de erro e mais parâmetros. Para ver a lista completa, consulte Códigos de erro REST do Partner Center.

Exemplos de REST

Exemplo de solicitação-resposta 1

Os detalhes para este exemplo de solicitação e resposta REST são os seguintes:

Fornecido por: OneTime
InvoiceLineItemType: UsageLineItems
Período: Anterior

Exemplo de solicitação 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

Importante

A partir de junho de 2023, a versão mais recente do SDK do .NET do Partner Center 3.4.0 foi arquivada. Você pode baixar o SDK no GitHub, juntamente com um arquivo README que contém informações úteis.

Os parceiros são incentivados a continuar a usar as APIs REST do Partner Center.

Exemplo de resposta 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"
    }
}

Exemplo de solicitação-resposta 2