Obter itens de linha de consumo comercial não faturados

Artigo
12/04/2024

Nota

A partir de 21 de janeiro de 2025, esta API será preterida. Planeje sua transição para garantir a continuidade.

Meta: recuperar itens de linha de uso diário não faturados para os períodos de faturamento atual e anterior antes de 21 de janeiro de 2025.
Ação: Use esta API antes de 21 de janeiro de 2025 ou mude para a API v2 GA mais cedo.
Meta: recuperar itens de linha de uso diário não faturados para os períodos de faturamento atual e anterior a partir de 21 de janeiro de 2025.
Ação: Use apenas a API v2 GA.

Para uma transição perfeita para as novas APIs, siga este link: API de reconciliação de uso nominal diária faturada e não faturada v2 (GA).

Obrigado pela sua atenção e estamos ansiosos para o seu sucesso contínuo com as nossas APIs de faturação.

Como obter uma coleção de detalhes de itens de linha de consumo comercial não faturados.

Você pode usar os seguintes métodos para obter uma coleção de detalhes, itens de linha de consumo comercial não faturados (também conhecidos como itens de linha de uso aberto) programaticamente.

Importante

Os dados de utilização diária nominal não incluem os encargos relativos a estes produtos:

Reserva do Azure
Plano de poupança do Azure
Office
Dynamics
Microsoft Power Apps
Software perpétuo
Subscrição de software
Produto SaaS que não é da Microsoft ou do marketplace

Nota

Você pode acessar seus itens de linha de uso diário não faturados por meio da API ou do portal do Partner Center. Para garantir a precisão dos dados, aguarde até 24 horas para disponibilidade. Dependendo da sua localização e quando os medidores relatam o uso, pode haver mais atrasos.

Primeiro, priorizamos a entrega pontual dos dados de uso diários faturados. Ocasionalmente, os dados de uso nominativos diários não faturados mais recentes podem não aparecer até que os dados faturados do mês anterior estejam disponíveis. Depois de receber os dados faturados, pode aceder a todos os dados de utilização não faturados atualizados desde o início do mês.

Pontos principais:

Aguarde até 24 horas para disponibilidade de dados.
Pode haver mais atrasos, dependendo da sua localização e dos tempos de reporte do medidor.
Os dados de uso nominal diário faturados são priorizados sobre os dados não faturados.

Sua compreensão e paciência são apreciadas à medida que nos esforçamos para fornecer as informações mais precisas e oportunas possíveis.

Pré-requisitos

Credenciais conforme descrito na autenticação do Partner Center. Este cenário oferece suporte à autenticação com credenciais autônomas de Aplicativo e Aplicativo+Usuário.

C#

Para obter os itens de linha para a fatura especificada:

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 de fatura.

O objeto de fatura contém todas as informações para a fatura especificada. O Provedor identifica a fonte das informações detalhadas não 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 InvoiceLineItems . 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 InvoiceDetail :

Passe BillingProvider e 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 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);
        }
    }
}

Para um exemplo semelhante, consulte:

Exemplo: Aplicativo de teste de console
Projeto: Exemplos de SDK do Partner Center
Classe: GetUnBilledConsumptionReconLineItemsPaging.cs

Pedido REST

Sintaxe da solicitação

Você pode usar as seguintes sintaxes para sua solicitação REST, dependendo do seu caso de uso. Para obter mais informações, consulte as descrições de cada sintaxe.

Método	URI do pedido	Descrição do caso de uso da sintaxe
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period} HTTP/1.1	Use esta sintaxe para retornar uma lista completa de cada item de linha para a fatura fornecida.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size} HTTP/1.1	Use esta sintaxe para faturas grandes. Use esta sintaxe com um tamanho especificado e deslocamento baseado em 0 para retornar uma lista paginada de itens de linha.
GET	{baseURL}/v1/invoices/unbilled/lineitems?provider=onetime&invoicelineitemtype=usagelineitems¤cycode={currencycode}&period={period}&size={size}&seekOperation=Next	Use esta sintaxe para obter a próxima página de itens de linha de reconciliação usando `seekOperation = "Next"`.

Parâmetros de URI

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

Nome	Type	Obrigatório	Description
fornecedor	string	Sim	O provedor: "OneTime".
tipo de item de linha de fatura	string	Sim	O tipo de detalhe da fatura: "UsageLineItems", "UsageLineItems".
currencyCode	string	Sim	O código de moeda para os itens de linha não faturados.
período	string	Sim	O período para recon não faturado (por exemplo: atual, anterior). Suponha que você precise consultar seus dados de uso não faturados do ciclo de faturamento (01/01/2020 – 31/01/2020) em janeiro, escolha período como "Atual", ou " Anterior".
size	Número	Não	O número máximo de itens a devolver. O tamanho padrão é 2000.
seekOperation	string	Não	Defina `seekOperation=Next` para obter a próxima página de itens de linha de reconciliação.

Cabeçalhos do pedido

Para obter mais informações, consulte Cabeçalhos REST do Partner Center.

Corpo do pedido

Nenhum.

Resposta do REST

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

Para o item de linha ChargeType, o valor Compra é mapeado para Novo e o valor Reembolso é mapeado para Cancelar.

Códigos de sucesso e erro de resposta

Cada resposta vem com um código de status HTTP que indica sucesso 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 obter a lista completa, consulte Códigos de erro REST do Partner Center.

Exemplos de solicitação-resposta

Exemplo de solicitação-resposta 1

Os seguintes detalhes aplicam-se a este exemplo:

Fornecedor: OneTime
InvoiceLineItemType: UsageLineItems
Período: Anterior

Exemplo de solicitação 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 partir de junho de 2023, a versão 3.4.0 mais recente do SDK do .NET do Partner Center foi arquivada. Você pode baixar a versão do SDK do 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": "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"
    }
}

Exemplo de solicitação-resposta 2