API de reconciliação de uso classificado diariamente faturado e não cobrado v2 (GA)

Aplica-se a: Partner Center (indisponível no Azure Governamental ou no Azure China 21Vianet.)

Nossa nova API assíncrona oferece uma maneira mais rápida e eficiente de acessar seus dados de cobrança e reconciliação por meio de blobs do Azure. Em vez de manter uma conexão aberta por horas ou processar lotes de 2.000 itens de linha, agora você pode simplificar seu fluxo de trabalho, reduzir a carga do servidor e melhorar os tempos de processamento de dados.

As novas APIs de reconciliação de uso classificado diariamente do comércio usam técnicas avançadas, como chave de manobrista e padrões assíncronos de solicitação-resposta . O padrão de chave de manobrista dá suporte ao acesso seguro aos recursos sem compartilhar credenciais, enquanto o padrão assíncrono de solicitação-resposta ajuda a habilitar a comunicação eficiente entre sistemas.

Essas APIs fornecem um token SAS (assinatura de acesso compartilhado) que você pode usar para acessar todos os atributos ou um subconjunto dos dados de reconciliação de uso classificado diariamente. Esse token aprimora a segurança concedendo acesso por tempo limitado e oferece flexibilidade no gerenciamento de permissões de acesso a dados.

Ao adotar nossas APIs otimizadas, você pode obter resultados mais rápidos com menos esforço, simplificar o acesso a dados e melhorar a eficiência geral. Abrace essas ferramentas para simplificar seu fluxo de trabalho e gerenciar permissões com mais eficiência.

Observação

As novas APIs não são hospedadas no host da API do Partner Center. Em vez disso, você pode encontrá-los no MS Graph em Usar a API do Microsoft Graph para exportar dados de cobrança de parceiros - Microsoft Graph v1.0 | Microsoft Learn. Para acessar essas APIs, consulte os detalhes a seguir.

Você só pode usar essas APIs para a nuvem global pública do MS Graph por enquanto. Eles ainda não estão disponíveis para o Azure Governo ou o Azure China.

Permitir que seu aplicativo acesse dados de cobrança de parceiros

Para permitir que seu aplicativo acesse dados de cobrança de parceiros, siga este link e familiarize-se com as noções básicas de autenticação e autorização para o Microsoft Graph. Essa etapa é crucial, pois garante que seu aplicativo possa acessar com segurança os dados necessários.

Atribuir permissão PartnerBilling.Read.All

Atribua a permissão "PartnerBilling.Read.All" usando o portal do Azure ou o Centro de administração do Microsoft Entra. Essas etapas garantem que seu aplicativo tenha o acesso necessário aos dados de cobrança do parceiro.

1. Registre seu aplicativo na home page do Microsoft Entra na seção Registros de aplicativo.
2. Conceda a permissão necessária acessando a página do Aplicativo Microsoft Entra. Na seção de permissões de API, selecione Adicionar uma permissão e escolha o escopo PartnerBilling.Read.All.

Entender as diferenças entre as versões beta e GA

Se você estiver usando nossa versão beta, provavelmente achará a transição para a versão de disponibilidade geral (GA) suave e intuitiva. Para ajudar você a entender as atualizações e melhorias, recomendamos comparar as versões beta e GA. Entender essas atualizações ajuda você a maximizar os novos recursos e melhorias disponíveis na versão GA.

Importante

O novo uso diário de comércio não inclui as cobranças por estes produtos:

• Reserva do Azure
• Plano de economia do Azure
• Office
• Dynamics
• Microsoft Power Apps
• Software perpétuo
• Assinatura de software
• Produto SaaS que não é da Microsoft ou do marketplace

Compreender e utilizar os endpoints da API

Para ajudar você a recuperar itens de linha de uso classificado diariamente de novo comércio faturados de forma assíncrona, oferecemos dois endpoints principais da API. Siga este guia simplificado para começar rapidamente.

Usar o ponto de extremidade de item de linha

Primeiro, use essa API para buscar novos itens de linha de uso diário de comércio . Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de localização com uma URL. Sonde essa URL regularmente até obter um status de êxito e uma URL de manifesto.

Usar o endpoint de status da operação

Seguindo estas etapas, você pode gerenciar com eficiência seu processo de reconciliação de faturas.

Continue verificando o status da operação chamando essa API em intervalos regulares. Se os dados não estiverem prontos, a resposta incluirá um cabeçalho Retry-After indicando quanto tempo esperar antes de tentar novamente. Depois que a operação for concluída, você receberá um recurso de manifesto com um link de pasta de armazenamento para baixar os dados de uso. A resposta segmenta os arquivos para melhorar a taxa de transferência e permitir o paralelismo de E/S.

Baixar dados de reconciliação

Aqui está um diagrama de sequência que mostra as etapas para baixar os dados de reconciliação.

Siga a sequência de ação do usuário

Aqui estão as etapas da sequência de ações do usuário para recuperar nova transação comercial itens de linha de reconciliação de uso classificados diariamente:

• enviar uma solicitação
• Verificar o status da solicitação
• Baixar itens de linha de reconciliação de uso com classificação diária do armazenamento de blobs do Azure

Enviar uma solicitação abaixo

Envie uma solicitação POST para o endpoint da API.

Receber itens de linha de uso classificado diariamente não faturados

Obtenha itens de linha de uso nominal diário não cobrado do novo comércio para o mês atual ou último ou período de faturamento.

Observação

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

Priorizamos primeiro a entrega pontual dos dados de uso classificados diariamente faturados. Ocasionalmente, os dados mais recentes de uso diário não faturado podem não aparecer até que os dados faturados do mês anterior estejam disponíveis. Depois de receber os dados cobrados, você poderá acessar todos os dados de uso não faturados atualizados desde o início do mês.

Pontos-chave:

• Aguarde até 24 horas para a disponibilidade de dados.
• Pode haver mais atrasos dependendo da localização e dos horários de relatório do medidor.
• Os dados de uso faturados diariamente são priorizados em relação aos dados não faturados.

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

Solicitação de API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export

Accept: application/json

Content-Type: application/json

{

"currencyCode": "USD",

"billingPeriod": "current",

"attributeSet": "basic"

}

Corpo da solicitação

Atributo	Obrigatório	Type	Descrição
conjunto de atributos	Falso	String	Escolha "completo" para todos os atributos ou "básico" para um conjunto limitado. Se não for especificado, "full" é o valor padrão. Verifique a lista de atributos nesta seção. Opcional.
billingPeriod	True	String	Para obter o uso com tarifa diária não faturado, use "atual" para o período de cobrança atual ou "anterior" para o período de cobrança anterior (o mesmo que "anterior" na API v1). Obrigatório.
currencyCode	True	String	Código da moeda de cobrança do parceiro. Obrigatório.

Cabeçalhos da solicitação

Para solicitar cabeçalhos para a API, consulte Confiabilidade e suporte.

Resposta da API

HTTP/1.1 202 Accepted  
Location: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

A API geralmente responde com um status HTTP 202. Você também pode encontrar outros status dependendo de suas solicitações. Esses status são listados na seção Status de resposta da API padrão.

Código	Descrição
202 – Aceito	Seu pedido foi aceito. Para verificar o status da sua solicitação, consulte a URL fornecida no cabeçalho do local.

Receber itens de linha de uso classificado diariamente cobrados

Obtenha itens de linha de uso classificado diariamente cobrados pelo novo comércio para uma fatura para o período de cobrança fechado.

Solicitação de API

POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export

{  
"invoiceId": "G00012345",  
"attributeSet": "full"  
}

Parâmetros de consulta

N/D

Corpo da solicitação

Atributo	Obrigatório	Type	Descrição
invoiceId	True	String	Um identificador exclusivo para cada fatura. Obrigatório.
conjunto de atributos	Falso	String	Escolha "completo" para todos os atributos ou "básico" para um conjunto limitado. Se não for especificado, "full" é o valor padrão. Verifique a lista de atributos nesta seção. Opcional.

Cabeçalho da solicitação

Cabeçalhos de solicitação para a API. Para saber mais, consulte a confiabilidade e o suporte.

Resposta da API

HTTP/1.1 202 Aceito
Local: https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Quando você usa a API, ela normalmente retorna um status HTTP 202. Para obter outros status possíveis com base em suas solicitações, confira status.

Código	Descrição
202 – Aceito	Seu pedido foi aceito. Para verificar o status da sua solicitação, consulte a URL fornecida no cabeçalho do local.

Verificar o status da solicitação

Para acompanhar o status de uma solicitação, verifique se você recebeu uma resposta HTTP 200 que é um código de status padrão que indica "bem-sucedido" ou "falhou". Se tiver êxito, você encontrará a URL do manifesto no atributo "resourceLocation". Esse atributo fornece um ponto de extremidade para acessar as informações necessárias.

Obter status da operação

Recupera o status de uma solicitação.

Solicitação de API

GET https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14

Parâmetros da solicitação

Nome	Incluir em	Obrigatório	Type	Descrição
operationId	URI da solicitação	True	String	Um identificador exclusivo para verificar o status da solicitação. Obrigatório.

Cabeçalho da solicitação

Para solicitar cabeçalhos para a API, consulte Confiabilidade e suporte.

Corpo da solicitação

N/D

Status da resposta

Além dos status HTTP padrão listados em Status de resposta da API padrão, a API também pode retornar o seguinte status HTTP:

Código	Descrição
410 - Desaparecido	O link do manifesto expira após um tempo definido. Para obter o link do manifesto novamente, envie uma nova solicitação.

Payload de resposta

A carga de resposta da API inclui os seguintes atributos:

Atributo	Obrigatório	Descrição
id	True	Um identificador exclusivo para cada resposta. Obrigatório.
status	True	Valores e ações: Obrigatório: não iniciado: aguarde o tempo especificado no cabeçalho "Retry-After" e realize outra chamada para verificar o status. executando: aguarde a duração especificada no cabeçalho "Repetir-Após" e, em seguida, realize uma nova chamada para verificar o status. succeeded: os dados estão prontos. Recupere a carga do manifesto usando o URI especificado em resourceLocation. failed: a operação falhou permanentemente. Reinicie-o.
createdDateTime	True	A hora em que a solicitação foi feita. Obrigatório.
lastActionDateTime	True	A última vez que o status foi alterado. Obrigatório.
resourceLocation	Falso	O URI para a carga do manifesto. Opcional.
erro	Falso	Detalhes sobre quaisquer erros, fornecidos no formato JSON. Opcional. Os atributos incluíram: message: Descrição do erro. code: O tipo de erro.

Objeto de localização do recurso

Atributo	Descrição
id	Um identificador exclusivo para o manifesto.
schemaVersion	Versão do esquema de manifesto.
dataFormat	Formato do arquivo de dados de faturamento. compressedJSON: formato de dados em que cada blob é um arquivo compactado que contém dados no formato de linhas JSON . Para recuperar os dados de cada blob, descompacte-os.
createdDateTime	Data e hora em que o arquivo de manifesto foi criado.
eTag	Versão dos dados do manifesto. Uma alteração nas informações de cobrança gera um novo valor.
partnerTenantId	ID do Microsoft Entra do locatário do parceiro.
diretório raiz	Diretório raiz do arquivo.
sasToken	Token SAS (assinatura de acesso compartilhado) que permite ler todos os arquivos no diretório.
partitionType	Divide os dados em vários blobs com base no atributo "partitionValue". O sistema divide as partições que excedem o número suportado. Por padrão, os dados são particionados com base no número de itens de linha no arquivo. Evite a codificação das contagens de itens de linha ou tamanhos de arquivo de maneira fixa, pois eles podem mudar.
blobCount	Número total de arquivos para essa ID de locatário de parceiro.
blobs	Uma matriz JSON de objetos "blob" que contêm os detalhes do arquivo para a ID do locatário do parceiro.
objeto blob	Um objeto que contém os seguintes detalhes: name e partitionValue
name	O nome do blob.
partitionValue	Partição que contém o arquivo. A partição grande é dividida em vários arquivos com base em determinados critérios, como tamanho do arquivo ou número de registros, com cada arquivo contendo o mesmo "partitionValue".

Solicitação de API

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A resposta recomenda aguardar 10 segundos antes de tentar novamente ao processar dados.

HTTP/1.1 200 OK  
Retry-After: 10  
{  
"id": "9ab9cb54-d07f-4f52-9ea6-a09d7de52c14",  
"createdDateTime": "2022-06-1T10-01-03.4Z",  
"lastActionDateTime": "2022-06-1T10-01-05Z",  
"status": "running"  
}

Solicitação de API

(10 segundos após a solicitação anterior...)

GET <https://graph.microsoft.com/v1.0/reports/partners/billing/operations/9ab9cb54-d07f-4f52-9ea6-a09d7de52c14>

Resposta da API

A API retorna o status "bem-sucedido" e o URI para "resourceLocation".

HTTP/1.1 200 OK  
Content-Type: application/json  
{

    "@odata.context": "https://graph.microsoft.com/v1.0/\$metadata#reports/partners/billing/operations/\$entity",

    "@odata.type": "#microsoft.graph.partners.billing.exportSuccessOperation",

    "id": "f2170b13-6a8e-47d6-b481-6988490dc0cb",

    "createdDateTime": "2023-12-05T21:17:29Z",

    "lastActionDateTime": "2023-12-05T21:18:00.8897902Z",

    "status": "succeeded",

    "resourceLocation": {

        "id": "44e8500b-ab92-490e-8ac3-90500a1d3427",

        "createdDateTime": "2023-11-06T19:58:47.513Z",

        "schemaVersion": "2",

        "dataFormat": "compressedJSON",

        "partitionType": "default",

        "eTag": "RwDrn7fbiTXy6UULE",

        "partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",

        "rootDirectory": "https://adlsreconbuprodeastus201.blob.core.windows.net/path_id",

        "sasToken": "{token}",

        "blobCount": 1,

        "blobs": \[

            {

                "name": "part-00123-5a93fa5d-749f-48bc-a372-9b021d93c3fa.c000.json.gz",

                "partitionValue": "default"

            }

        \]

    }

}

Baixar itens de linha de reconciliação de uso com classificação diária do armazenamento de blobs do Azure

Primeiro, você precisa obter o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs. Você pode encontrar esses detalhes nas propriedades sasToken e rootDirectory da resposta da API de conteúdo do manifesto. Em seguida, para baixar e descompactar o arquivo de blob, use o SDK/ferramenta de Armazenamento do Azure. Está no formato JSONLines .

Dica

Certifique-se de verificar nosso código de amostra. Ele mostra como baixar e descompactar o arquivo de blob do Azure em seu banco de dados local.

Entender os status de resposta da API padrão

Você pode receber estes status HTTP da resposta da API:

Código	Descrição
400 - Solicitação Incorreta	A solicitação está ausente ou contém dados incorretos. Verifique o corpo da resposta para obter detalhes do erro.
401 - Não Autorizado	A autenticação é necessária antes de fazer a primeira chamada. Autentique com o serviço de API do parceiro.
403 - Forbidden	Você não tem a autorização necessária para fazer a solicitação.
404 - Não encontrado	Os recursos solicitados não estão disponíveis com os parâmetros de entrada fornecidos.
410 - Desaparecido	O link do manifesto não é mais válido ou ativo. Envie uma nova solicitação.
500 – Erro interno do servidor	A API ou suas dependências não podem atender à solicitação no momento. Tente novamente depois.
5000 – Nenhum dado disponível	O sistema não possui dados para os parâmetros de entrada fornecidos.

Comparar as versões beta e GA

Confira a tabela de comparação a seguir para ver as diferenças entre as versões beta e GA (disponibilidade geral). Se você estiver usando a versão beta no momento, a transição para a versão ga provavelmente será simples e fácil.

Informações importantes	Beta	Disponível para o público geral
Ponto de extremidade do host da API	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/
Método HTTP	POST	POST
Endpoint da API de uso classificado diário não cobrado	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/unbilled/export
Parâmetros de entrada para a API de uso nominal diário não faturado	Para especificar parâmetros na solicitação de API, inclua-os na string de consulta do URL da solicitação. Por exemplo, para especificar os parâmetros period e currencyCode, anexe ?period=current&currencyCode=usd à URL da solicitação.	Para fornecer entradas, inclua um objeto JSON no corpo da solicitação. Seu JSON deve ter as seguintes propriedades: * currencyCode: sua moeda de cobrança. Por exemplo, USD. * billingPeriod: o período de cobrança da fatura. Por exemplo, atual. Aqui está um exemplo de objeto JSON que inclui as propriedades currencyCode e billingPeriod:<br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>}
Endpoint da API de uso classificado diário faturado	https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{InvoiceId}	https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
Parâmetros de entrada para a API de uso diário faturado	Para especificar parâmetros na solicitação de API, inclua o invoiceId no URL da solicitação. Além disso, você pode incluir um parâmetro de fragmento opcional na cadeia de caracteres de consulta para recuperar o conjunto completo de atributos. Por exemplo, para recuperar o conjunto completo de atributos, anexe ?fragment=full à URL da solicitação.	Para fornecer entradas, inclua um objeto JSON no corpo da solicitação. Seu JSON deve ter as seguintes propriedades: * invoiceId: o identificador exclusivo da fatura. Por exemplo, G00012345. * attributeSet: Os atributos que devem estar na resposta, como full. Aqui está um exemplo de objeto JSON que inclui as propriedades invoiceId e attributeSet: {<br> "invoiceId": "G00012345",<br> "attributeSet": "full"<br>}
Recurso de manifesto	Use um método GET /manifests/{id} separado para recuperar o recurso de manifesto.	Use o método GET /operations/{Id} para acessar o recurso de manifesto em resourceLocation. Esse método economiza tempo eliminando a necessidade de uma chamada separada para GET /manifests/{id}.
Alterações no esquema de manifesto
	"id": Não disponível	"id": um identificador exclusivo para o recurso de manifesto.
	"versão": Disponível	"version": alterado para "schemaversion".
	"dataFormat": Disponível	"dataFormat": Disponível.
	"utcCretedDateTime": Disponível	"utcCretedDateTime": alterado para "createdDateTime".
	"eTag": Disponível	"eTag": Disponível.
	"partnerTenantId": Disponível	"partnerTenantId": Disponível
	"rootFolder": Disponível	"rootFolder": alterado para "rootDirectory".
	"rootFolderSAS": Disponível	"rootFolderSAS": alterado para "sasToken". Esta atualização fornece apenas o token sem o caminho do diretório raiz. Para localizar o diretório, use a propriedade "rootDirectory".
	"partitionType": Disponível	"partitionType": Disponível.
	"blobCount": Disponível	"blobCount": Disponível.
	"sizeInBytes": Disponível	"sizeInBytes": Não disponível.
	"blobs": Disponível	"blobs": Disponível.
	"blob object": Disponível	"blob object": Disponível.
	"name": Disponível	"name": Disponível.
	"partitionValue": Disponível	"partitionValue": Disponível.

Comparar os atributos do item de linha de reconciliação de uso avaliado diariamente

Para comparar os atributos retornados pela API de reconciliação de uso cobrada ou não faturada para os conjuntos de atributos "completos" ou "básicos", consulte esta tabela. Para obter mais informações sobre esses atributos e seus significados, consulte os campos de no arquivo de reconciliação de uso com classificação diária.

Atributo	Completo	Basic
PartnerId	sim	sim
PartnerName	sim	sim
CustomerId	sim	sim
CustomerName	sim	Sim
CustomerDomainName	sim	não
CustomerCountry	sim	não
MpnId	sim	não
Tier2MpnId	sim	não
InvoiceNumber	sim	sim
ProductId	sim	sim
SkuId	sim	sim
AvailabilityId	sim	não
SkuName	sim	sim
ProductName	sim	não
PublisherName	sim	sim
PublisherId	sim	não
SubscriptionDescription	sim	não
SubscriptionId	sim	sim
ChargeStartDate	sim	sim
ChargeEndDate	sim	sim
UsageDate	sim	sim
MeterType	sim	não
MeterCategory	sim	não
MeterId	sim	não
MeterSubCategory	sim	não
MeterName	sim	não
MeterRegion	sim	não
Unidade	sim	sim
ResourceLocation	sim	não
ConsumedService	sim	não
ResourceGroup	sim	não
ResourceURI	sim	sim
ChargeType	sim	sim
UnitPrice	sim	sim
Quantidade	sim	sim
UnitType	sim	não
BillingPreTaxTotal	sim	sim
BillingCurrency	sim	sim
PricingPreTaxTotal	sim	sim
PricingCurrency	sim	sim
ServiceInfo1	sim	não
ServiceInfo2	sim	não
Marcações	sim	não
AdditionalInfo	sim	não
EffectiveUnitPrice	sim	sim
PCToBCExchangeRate	sim	sim
PCToBCExchangeRateDate	sim	não
EntitlementId	sim	sim
EntitlementDescription	sim	não
PartnerEarnedCreditPercentage	sim	não
CreditPercentage	sim	sim
CreditType	sim	sim
BenefitOrderID	sim	sim
BenefitID	sim	não
BenefitType	sim	sim

Importante

Anote essas alterações ao mover da API v1 para a v2.

• Cada nome de atributo agora começa com um letra minúsculapara manter a consistência com o arquivo e melhorar a legibilidade.

• unitOfMeasure é atualizado para Unit. Seu significado e valor permanecem inalterados, simplificando o nome do atributo.

• resellerMpnId agora é Tier2MpnId. O significado e o valor são os mesmos.

• rateOfPartnerEarnedCredit é atualizado para PartnerEarnedCreditPercentage. O novo nome e o valor agora refletem a porcentagem em vez da fração, facilitando a compreensão. Por exemplo, 0,15 agora é 15%.

• rateOfCredit agora é CreditPercentage. O nome e o valor foram alterados para fornecer uma compreensão mais clara. Por exemplo, 1,00 agora é 100%.

Acreditamos que essas mudanças tornam as APIs mais intuitivas e fáceis de usar.

Obter código de exemplo

Para usar essa API, consulte o link a seguir, que inclui o código de exemplo C#.

Exemplos de API do Partner Center: obter dados de reconhecimento de cobrança.