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.)
Nossas APIs assíncronas oferecem uma maneira mais rápida e gerenciável de acessar dados de cobrança e reconciliação por meio de blobs do Azure. Com essas APIs, você não precisa manter a conexão aberta por horas ou percorrer os lotes de 2.000 itens de linha.
Otimizamos nossas novas APIs de reconciliação de uso classificado diariamente de comércio usando chave de manobrista e padrões assíncronos de solicitação-resposta . Ao usar essas APIs, você recebe um token que pode ser usado para acessar todos os atributos ou um subconjunto dos dados de reconciliação de uso classificado diariamente.
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ê pode usar essas APIs para a nuvem pública/global do MS Graph somente agora. Ela ainda não está disponível para o Azure Governamental nem para o Azure China 21Vianet.
Importante
Para conceder ao seu aplicativo a permissão necessária para acessar os dados de cobrança do parceiro, você precisa seguir este link e saber mais sobre os conceitos básicos de autenticação e autorização do Microsoft Graph.
Normalmente, você pode usar o portal do Azure ou o Centro de administração do Entra para atribuir a permissão necessária: "PartnerBilling.Read.All". Aqui estão as etapas para fazer isso:
- Registre seu aplicativo na home page do Microsoft Entra na seção Registros de aplicativo.
- Atribua permissão ao seu aplicativo na página Aplicativo Microsoft Entra na seção Permissões de API. Selecione "Adicionar uma permissão" e escolha o escopo "PartnerBilling.Read.All".
Observação
Se você estiver usando nossa versão beta, talvez não perceba mudanças significativas na versão GA (disponível ao público em geral). Recomendamos comparar as duas versões para entender as diferenças e atualizações.
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
Visão geral da API
Para recuperar itens de linha de uso classificado diariamente do novo comércio de forma assíncrona, use dois endpoints de API. Veja o processo:
Ponto de extremidade do item de linha de uso
Use essa API para recuperar itens de linha de uso classificado diariamente faturados ou não faturados. Você obtém um status HTTP 202 e uma URL no cabeçalho do local. Sonde essa URL em intervalos regulares até receber um status de êxito com uma URL de manifesto.
Ponto de extremidade de status da operação
Para obter um status de sucesso, continue chamando essa API em intervalos regulares. Se os dados não estiverem prontos, a resposta da API incluirá um cabeçalho Retry-After para informar quanto tempo esperar antes de tentar novamente. Quando a operação for concluída, você obterá um recurso de manifesto com uma pasta de armazenamento na qual poderá baixar os dados de uso. A resposta divide os arquivos em partes menores para otimizar a taxa de transferência e o paralelismo de E/S.
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 itens de linha de reconciliação de uso classificado diariamente para novos comércios , siga estas etapas:
Etapa 1: enviar solicitação
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 dados precisos, aguarde 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, talvez você não veja os dados de uso diário não cobrado mais recentes até que os dados de uso faturado do mês anterior estejam disponíveis. Depois de receber os dados de uso faturados, você poderá recuperar todos os dados de uso não faturados atualizados desde o início do mês.
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. O valor padrão é "full". (Veja a lista de atributos aqui). Opcional. |
billingPeriod | True | String | Use "atual" ou "último" (o mesmo que "anterior" nas APIs V1) para obter o uso nominal diário para o mês atual ou o último mês ou período de cobrança. Obrigatória. |
currencyCode | True | String | Código da moeda de cobrança do parceiro. Obrigatória. |
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
Quando você usa a API, ela normalmente retorna um status HTTP 202. Para ver outros status possíveis com base em suas solicitações, consulte 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ória. |
conjunto de atributos | Falso | String | Escolha "completo" para todos os atributos ou "básico" para um conjunto limitado. O valor padrão é "full". (Veja a lista de atributos aqui). 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 outros status possíveis com base em suas solicitações, consulte 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. |
Etapa 2: verificar o status da solicitação
Para verificar o status de uma solicitação, aguarde uma resposta HTTP 200 com um status de "bem-sucedido" ou "falha". Se a solicitação for bem-sucedida, a URL do manifesto será fornecida no atributo "resourceLocation".
Obter status da operação
Recupera o status de uma solicitação.
Solicitação de API
Parâmetros da solicitação
Nome | Incluir em | Obrigatório | Type | Descrição |
---|---|---|---|---|
operationId | URI da solicitação | True | String | Uma ID exclusiva para verificar o status da solicitação. Obrigatória. |
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, a API pode retornar o seguinte status HTTP:
Código | Descrição |
---|---|
410 - Desaparecido | O link de manifesto só está ativo por uma duração específica definida pelo servidor. Após esse tempo, você deve enviar uma nova solicitação para acessar o manifesto. |
Payload de resposta
A carga de resposta da API inclui os seguintes atributos:
Atributo | Obrigatório | Descrição |
---|---|---|
id | Verdadeiro | Um ID exclusivo para cada resposta. Obrigatória. |
status | Verdadeiro | Valores e ações (obrigatório): notstarted: aguarde o tempo especificado no cabeçalho "Retry-After" e faça outra chamada para verificar o status. running: aguarde o tempo especificado no cabeçalho "Retry-After" e faça outra 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 | Verdadeiro | A hora em que a solicitação foi feita. Obrigatória. |
lastActionDateTime | Verdadeiro | A hora em que o status foi alterado pela última vez. Obrigatória. |
resourceLocation | Falso | O URI para a carga do manifesto. Opcional. |
erro | Falso | Se a operação falhar, os detalhes do erro serão fornecidos no formato JSON. Opcional. Os seguintes atributos podem ser incluídos: mensagem (Obrigatório): uma descrição detalhada do erro. code (Obrigatório): o tipo de erro que ocorreu. |
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 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. Não defina um número fixo de itens de linha ou tamanho de arquivo no código, pois esses valores 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 | O nome do blob. |
partitionValue | Partição que contém o arquivo. A partição grande é dividida em vários arquivos, 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": "0e195b37-4574-4539-bc42-0e539b9684c0",
"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 classificado diariamente do armazenamento de blobs do Azure
Obtenha o token SAS (assinatura de acesso compartilhado) e o local de armazenamento de blobs das propriedades "sasToken" e "rootDirectory" da resposta da API de conteúdo do manifesto. Use o SDK/ferramenta do Armazenamento do Azure para baixar e descompactar o arquivo de blob. Está no formato JSONLines .
Dica
Confira nosso código de exemplo para baixar e descompactar o arquivo de blob do Azure em seu banco de dados local.
Status de resposta padrão da API
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 | O chamador não está autenticado e você deve se autenticar com o serviço de API do parceiro antes de fazer a primeira chamada. |
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 do manifesto expirou ou expirou. Envie uma nova solicitação. |
500 – Erro de servidor interno | A API ou uma de suas dependências não pode atender à solicitação no momento. Tente novamente depois. |
5000 – Dados não disponíveis | O sistema não possui dados para os parâmetros de entrada fornecidos. |
Comparar as versões beta e GA
Consulte a tabela de comparação para entender as diferenças entre as versões beta e GA (disponibilidade geral). Se você estiver usando a versão beta, mudar para a versão GA deve ser simples.
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 | POSTAR |
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¤cyCode=usd à URL da solicitação. |
Para fornecer entradas, inclua um objeto JSON no corpo da solicitação. O objeto JSON deve conter as seguintes propriedades: * currencyCode: o código da moeda da fatura. Por exemplo, USD. * billingPeriod: o período de cobrança da fatura. Por exemplo, atual. Aqui está um exemplo de um 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. O objeto JSON deve conter as seguintes propriedades: * invoiceId: a ID da fatura. Por exemplo, G00012345. * attributeSet: o conjunto de atributos a serem incluídos na resposta. Por exemplo, cheio. Aqui está um exemplo de um 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}, que retorna o recurso de manifesto relacionado em resourceLocation, eliminando a necessidade de uma chamada separada para o método 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": renomeado para "schemaversion". | |
"dataFormat": Disponível | "dataFormat": Disponível. | |
"utcCretedDateTime": Disponível | "utcCretedDateTime": renomeado para "createdDateTime". | |
"eTag": Disponível | "eTag": Disponível. | |
"partnerTenantId": Disponível | "partnerTenantId": Disponível | |
"rootFolder": Disponível | "rootFolder": renomeado para "rootDirectory". | |
"rootFolderSAS": Disponível | "rootFolderSAS": renomeado para "sasToken". Ele agora fornece um token e não inclui mais o caminho do diretório raiz. Para acessar 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. |
Atributos de item de linha de reconciliação de uso avaliado diariamente
Para comparar os atributos retornados pela API de reconciliação de uso classificado diariamente para os conjuntos de atributos "completos" ou "básicos", consulte as informações a seguir. Para saber mais sobre esses atributos, consulte esta documentação.
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 |
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 migrar para a API v2 da v1.
O nome de cada atributo começa em maiúsculas.
unitOfMeasure agora é Unit. O significado e o valor do atributo são os mesmos.
resellerMpnId agora é Tier2MpnId. O significado e o valor do atributo são os mesmos.
O nome e o valor de rateOfPartnerEarnedCredit foram alterados para PartnerEarnedCreditPercentage. O novo nome e valor do atributo refletem a porcentagem em vez da fração. Por exemplo, 0,15 agora é 15.
rateOfCredit agora é CreditPercentage. O significado e o valor do atributo foram alterados. Por exemplo, 1,00 agora é 100.
Código de exemplo
Para saber mais, confira Exemplos de API do Partner Center: obter dados de reconhecimento de cobrança.