API de reconciliação de uso nominal diária faturada e não faturada v2 (GA)
Aplica-se a: Partner Center (indisponível no Azure Government 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 diário 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 permite acesso seguro a recursos sem compartilhar credenciais, enquanto o padrão assíncrono solicitação-resposta permite uma comunicação eficiente entre sistemas.
Essas APIs fornecem um token de assinatura de acesso compartilhado (SAS) que você pode usar para acessar todos os atributos ou um subconjunto dos dados de reconciliação de uso avaliado diariamente. Esse token aumenta 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 aos dados e melhorar a eficiência geral. Adote essas ferramentas para simplificar seu fluxo de trabalho e gerenciar permissões de forma mais eficaz.
Nota
As novas APIs não estã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 faturamento de parceiros - Microsoft Graph v1.0 | Microsoft Learn. Para acessar essas APIs, consulte os seguintes detalhes.
Você pode usar essas APIs para a nuvem pública/global do MS Graph somente agora. Eles ainda não estão disponíveis para o Azure Government ou Azure China 21Vianet.
Importante
Para permitir que seu aplicativo acesse os dados de cobrança do parceiro, siga este link e familiarize-se com as noções básicas de autenticação e autorização do Microsoft Graph. Esta etapa é crucial, pois garante que seu aplicativo possa acessar com segurança os dados necessários.
Você pode atribuir a permissão "PartnerBilling.Read.All" usando o portal do Azure ou o Centro de administração do Entra. Saiba como:
- Registe a sua aplicação na página inicial do Microsoft Entra na secção Registos de aplicações.
- Para conceder a permissão necessária, vá para a página Microsoft Entra App. Na seção Permissões da API, selecione "Adicionar uma permissão" e escolha o escopo "PartnerBilling.Read.All".
Ao concluir estas etapas, você garante que seu aplicativo tenha o acesso necessário aos dados de faturamento do parceiro.
Nota
Se você estiver usando nossa versão beta, é provável que ache a transição para a versão de disponibilidade geral (GA) suave e intuitiva. Para ajudá-lo a entender as atualizações e melhorias, recomendamos comparar as versões beta e GA. Compreender essas atualizações ajudará você a maximizar os novos recursos e melhorias disponíveis na versão GA.
Importante
O novo uso diário do comércio não inclui as taxas para 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
Descrição Geral da API
Para ajudá-lo a recuperar novos itens de linha de uso diários de comércio faturados de forma assíncrona, oferecemos dois pontos de extremidade de API principais. Siga este guia simplificado para começar de forma rápida e eficiente!
Ponto de extremidade de item de linha de uso
Primeiro, use essa API para buscar novos itens de linha de uso com classificação diária de comércio . Ao fazer uma solicitação, você recebe um status HTTP 202 e um cabeçalho de local com uma URL. Analise este URL regularmente até obter um status de sucesso e um URL de manifesto.
Ponto de extremidade do status da operação
Em seguida, 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. Quando a operação estiver 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 paralelismo de E/S.
Seguindo estas etapas, você pode gerenciar com eficiência seu processo de reconciliação de faturas.
Diagrama de sequência
Aqui está um diagrama de sequência que mostra as etapas para baixar os dados de reconciliação.
Sequência de ação do usuário
Para recuperar novos itens de linha de reconciliação de uso diário do comércio , siga estas etapas:
Passo 1: Submeter pedido
Envie uma solicitação POST para o ponto de extremidade da API.
Obter itens de linha de uso com classificação diária não faturada
Obtenha novos itens de linha de uso diário não faturados para o mês ou período de faturamento atual ou último do calendário.
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. Por vezes, os dados de utilização diária tarifada mais recentes não faturados podem não surgir até que os dados faturados do mês anterior se tornem 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 comunicação 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.
Pedido da 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 do pedido
| Atributo | Necessário | Type | Description |
|---|---|---|---|
| attributeSet | False | 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. |
| faturamentoPeríodo | True | String | Para obter o uso nominal diário não faturado, use "atual" para o período de faturamento atual ou "último" para o período de faturamento anterior (o mesmo que "anterior" na API v1). Necessário. |
| currencyCode | True | String | Código da moeda de cobrança do parceiro. Necessário. |
Cabeçalhos do pedido
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 estão listados na seção Status de resposta padrão da API.
| Código | Description |
|---|---|
| 202 – Aceito | O seu pedido foi aceite. Para verificar o estado do seu pedido, consulte o URL fornecido no cabeçalho da localização. |
Obter itens de linha de uso classificados diariamente cobrados
Obtenha novos itens de linha de uso diários faturados diariamente para uma fatura para o período de faturamento fechado.
Pedido da API
POST https://graph.microsoft.com/v1.0/reports/partners/billing/usage/billed/export
{
"invoiceId": "G00012345",
"attributeSet": "full"
}
Parâmetros de consultas
N/A
Corpo do pedido
| Atributo | Necessário | Type | Description |
|---|---|---|---|
| invoiceId | True | String | Um identificador exclusivo para cada fatura. Necessário. |
| attributeSet | False | 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 do pedido
Solicitar cabeçalhos para a API. Para saber mais, consulte a confiabilidade e o suporte.
Resposta da API
HTTP/1.1 202 Aceito
Localização: 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 nas suas solicitações, consulte status.
| Código | Description |
|---|---|
| 202 – Aceito | O seu pedido foi aceite. Para verificar o estado do seu pedido, consulte o URL fornecido no cabeçalho da localização. |
Etapa 2: Verificar o status da solicitação
Para acompanhar o status de uma solicitação, certifique-se de receber uma resposta HTTP 200, que é um código de status padrão indicando "bem-sucedido" ou "reprovado". Se for bem-sucedido, você encontrará a URL do manifesto no atributo "resourceLocation". Este atributo fornece um ponto de extremidade para acessar as informações necessárias.
Obter o status da operação
Recupera o status de uma solicitação.
Pedido da API
Parâmetros de solicitação
| Nome | Incluir em | Necessário | Type | Description |
|---|---|---|---|---|
| operationId | URI do pedido | True | String | Um identificador exclusivo para verificar o status da solicitação. Necessário. |
Cabeçalho do pedido
Para solicitar cabeçalhos para a API, consulte Confiabilidade e suporte.
Corpo do pedido
N/A.
Estado 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 | Description |
|---|---|
| 410 – Desaparecido | O link de manifesto expira após um tempo definido. Para obter o link do manifesto novamente, envie uma nova solicitação. |
Carga útil de resposta
A carga útil de resposta da API inclui os seguintes atributos:
| Atributo | Necessário | Description |
|---|---|---|
| id | True | Um identificador exclusivo para cada resposta. Necessário. |
| status | True |
Valores e ações: Obrigatório: notstarted: Aguarde a duração especificada no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. executando: Aguarde a duração especificada no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. bem-sucedido: os dados estão prontos. Recupere a carga útil do manifesto usando o URI especificado em resourceLocation. falhou: A operação falhou permanentemente. Reinicie-o. |
| createdDateTime | True | A hora em que o pedido foi feito. Necessário. |
| lastActionDateTime | True | A última vez que o status mudou. Necessário. |
| resourceLocation | False | O URI para a carga útil do manifesto. Opcional. |
| error | False | Detalhes sobre quaisquer erros, fornecidos no formato JSON. Opcional. Atributos incluídos: message: Descrição do erro. code: O tipo de erro. |
Objeto de local de recurso
| Atributo | Description |
|---|---|
| id | Um identificador exclusivo para o manifesto. |
| schemaVersion | Versão do esquema de manifesto. |
| dataFormat | Formato do ficheiro de dados de faturação. compressedJSON: formato de dados onde 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 faturamento gera um novo valor. |
| partnerTenantId | ID do Microsoft Entra do locatário do parceiro. |
| rootDirectory | Diretório raiz do arquivo. |
| sasToken | Token SAS (assinatura de acesso compartilhado) que permite ler todos os arquivos no diretório. |
| Tipo de partição | Divide os dados em vários blobs com base no atributo "partitionValue ". O sistema divide 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 codificar contagens de itens de linha ou tamanhos de arquivo, pois eles podem mudar. |
| blobContagem | Número total de ficheiros para este ID de inquilino parceiro. |
| blobs | Uma matriz JSON de objetos "blob" que contêm os detalhes do arquivo para a ID do locatário parceiro. |
| objeto blob | Um objeto que contém os seguintes detalhes: name e partitionValue |
| nome | Nome do blob. |
| partitionValue | Partição que contém o arquivo. A partição grande é dividida em vários arquivos com base em certos critérios, como tamanho do arquivo ou número de registros, com cada arquivo contendo o mesmo "partitionValue". |
Pedido da 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"
}
Pedido da API
(10 segundos após o pedido 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 de "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"
}
\]
}
}
Etapa 3: Baixar itens de linha de reconciliação de uso com classificação diária do armazenamento de blob do Azure
Primeiro, você precisa obter o token de assinatura de acesso compartilhado (SAS) e o local de armazenamento de blob. Você pode encontrar esses detalhes nas propriedades "sasToken" e "rootDirectory" da resposta da API de carga útil do manifesto. Em seguida, para baixar e descompactar o arquivo blob, use o SDK/ferramenta de Armazenamento do Azure. Está no formato JSONLines .
Gorjeta
Certifique-se de verificar nosso código de exemplo. Ele mostra como baixar e descompactar o arquivo de blob do Azure para seu banco de dados local.
Status de resposta padrão da API
Você pode receber esses status HTTP da resposta da API:
| Código | Descrição |
|---|---|
| 400 – Mau Pedido | O pedido está em falta 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-se com o serviço de API do parceiro. |
| 403 – Proibido | 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 de 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 mais tarde. |
| 5000 – Dados não disponíveis | O sistema não tem dados para os parâmetros de entrada fornecidos. |
Compare as versões beta e GA
Confira a tabela de comparação para ver as diferenças entre as versões beta e geralmente disponível (GA). Se você estiver usando a versão beta, a transição para a versão GA é simples e fácil.
| Informação importante | Beta | Disponibilidade 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 |
| Ponto de extremidade da API de uso diário não faturado | 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 cadeia de caracteres de consulta da URL da solicitação. Por exemplo, para especificar os parâmetros period e currencyCode, anexe ?period=current¤cyCode=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: A sua moeda de faturação. Por exemplo, USD. * billingPeriod: O período de faturamento da fatura. Por exemplo, atual. Aqui está um objeto JSON de exemplo que inclui as propriedades currencyCode e billingPeriod: <br>{<br> "currencyCode": "USD",<br> "billingPeriod": "current"<br>} |
| Ponto de extremidade da API de uso avaliado diário cobrado | 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 nominal diário faturado | Para especificar parâmetros na solicitação de API, inclua o invoiceId na 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, acrescente ?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 objeto JSON de exemplo 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. | |
| "nome": Disponível | "nome": Disponível. | |
| "partitionValue": Disponível | "partitionValue": Disponível. |
Atributos de item de linha de reconciliação de uso diário
Para comparar os atributos retornados pela API de reconciliação de utilização faturada ou não faturada para os conjuntos de atributos "completo" ou "básico", consulte esta tabela. Para saber mais sobre esses atributos e seus significados, consulte esta documentação .
| Atributo | Total | Básica |
|---|---|---|
| Identificação do parceiro | sim | sim |
| PartnerName | sim | sim |
| ID do Cliente | sim | sim |
| CustomerName | sim | Sim |
| CustomerDomainName | sim | não |
| País do Cliente | sim | não |
| MpnId | sim | não |
| Tier2MpnId | sim | não |
| Número da fatura | sim | sim |
| ProductId | sim | sim |
| SkuId | sim | sim |
| AvailabilityId | sim | não |
| SkuName | sim | sim |
| ProductName | sim | não |
| Nome do Editor | sim | sim |
| PublisherId | sim | não |
| SubscriçãoDescrição | 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 |
| Unit | 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 |
| Tipo de Unidade | sim | não |
| FaturamentoPreTaxTotal | sim | sim |
| BillingCurrency | sim | sim |
| PreçosPreTaxTotal | sim | sim |
| PricingCurrency | sim | sim |
| ServiceInfo1 | sim | não |
| ServiceInfo2 | sim | não |
| Etiquetas | sim | não |
| AdditionalInfo | sim | não |
| EffectiveUnitPrice | sim | sim |
| PCToBCExchangeRate | sim | sim |
| PCToBCExchangeRateDate | sim | não |
| EntitlementId | sim | sim |
| DireitoDescrição | sim | não |
| ParceiroGanhoCréditoPercentagem | sim | não |
| CreditPercentage | sim | sim |
| Tipo de Crédito | sim | sim |
| BenefitOrderID | sim | sim |
| ID do Benefício | sim | não |
| Tipo de Benefício | sim | sim |
Importante
Anote essas alterações ao mudar da API v1 para a v2.
Cada nome de atributo agora começa com uma letra maiúscula para 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 valor agora refletem a porcentagem em vez da fração, facilitando a compreensão. Por exemplo, 0,15 é agora 15%.
rateOfCredit agora é CreditPercentage. Tanto o nome como o valor foram alterados para proporcionar 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.
Código de exemplo
Para usar essa API, consulte o link a seguir, que inclui código de exemplo em C#.
Exemplos de API do Partner Center: obtenha dados de reconhecimento de faturamento.