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.)
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 diário 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 avaliado diariamente.
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 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 as noções básicas 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 os passos para fazê-lo:
- Registe a sua aplicação na página inicial do Microsoft Entra na secção Registos de aplicações.
- Atribua permissão ao seu aplicativo na página Aplicativo Microsoft Entra na seção Permissões da API. Selecione "Adicionar uma permissão" e escolha o escopo "PartnerBilling.Read.All".
Nota
Se estiver a utilizar a nossa versão beta, poderá não notar alterações significativas na versão geralmente disponível (GA). Recomendamos comparar as duas versões para entender as diferenças e atualizações.
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
Descrição Geral da API
Para recuperar novos itens de linha de uso diário de comércio de forma assíncrona, use dois pontos de extremidade de API. Segue-se o processo:
Ponto de extremidade de item de linha de uso
Use esta API para recuperar itens de linha de uso diário faturados ou não faturados. Você obtém um status HTTP 202 e uma URL no cabeçalho do local. Sonde este URL em intervalos regulares até receber um status de êxito com um URL de manifesto.
Ponto de extremidade do status da operação
Para obter um status de sucesso, continue chamando essa API em um intervalo regular. 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 estiver concluída, você obterá um recurso de manifesto com uma pasta de armazenamento onde poderá baixar os dados de uso. A resposta divide os arquivos em partes menores para taxa de transferência otimizada e 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 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.
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. O valor padrão é "full". (Veja a lista de atributos aqui). Opcional. |
| faturamentoPeríodo | True | String | Use "atual" ou "último" (o mesmo que "anterior" nas APIs V1) para obter o uso nominal diário para o mês ou período de faturamento atual ou passado. Obrigatório. |
| currencyCode | True | String | Código da moeda de cobrança do parceiro. Obrigató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
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 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. Obrigatório. |
| attributeSet | False | 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 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 outros status possíveis com base em 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 verificar o status de uma solicitação, aguarde uma resposta HTTP 200 com o status "bem-sucedido" ou "falhou". Se a solicitação for bem-sucedida, a URL do manifesto será fornecida no atributo "resourceLocation".
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 ID exclusivo para verificar o status da solicitação. Obrigató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, a API pode retornar o seguinte status HTTP:
| Código | Description |
|---|---|
| 410 – Desaparecido | O link de manifesto só está ativo por uma duração específica definida pelo servidor. Decorrido este tempo, deve apresentar um novo pedido de acesso ao manifesto. |
Carga útil de resposta
A carga útil de resposta da API inclui os seguintes atributos:
| Atributo | Necessário | Descrição |
|---|---|---|
| id | True | Um ID exclusivo para cada resposta. Obrigatório. |
| status | True | Valores e ações (obrigatório): notstarted: aguarde o tempo especificado no cabeçalho "Retry-After" e, em seguida, faça outra chamada para verificar o status. Em execução: aguarde o tempo especificado 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. Obrigatório. |
| lastActionDateTime | True | A hora em que o status foi alterado pela última vez. Obrigatório. |
| resourceLocation | False | O URI para a carga útil do manifesto. Opcional. |
| error | False | 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 local de recurso
| Atributo | Descrição |
|---|---|
| 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 inquilino 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. Não defina um número fixo de itens de linha ou tamanho de arquivo no código, pois esses valores 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: |
| nome | 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". |
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": "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 com classificação diária do armazenamento de blob do Azure
Obtenha o token de assinatura de acesso compartilhado (SAS) e o local de armazenamento de blob das propriedades "sasToken" e "rootDirectory" da resposta da API de carga útil do manifesto. Use o SDK/ferramenta de Armazenamento do Azure para baixar e descompactar o arquivo de blob. Está no formato JSONLines .
Gorjeta
Confira nosso código de exemplo para 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 | O chamador não é autenticado e você deve 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 de manifesto expirou ou expirou. Envie uma nova solicitação. |
| 500 – Erro interno do servidor | A API ou uma de suas dependências não pode 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
Consulte a tabela de comparação para entender as diferenças entre as versões beta e geralmente disponível (GA). Se você estiver usando a versão beta, mudar para a versão GA deve ser simples.
| 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. O objeto JSON deve conter as seguintes propriedades: * currencyCode: O código de moeda para a fatura. Por exemplo, USD. * billingPeriod: O período de faturamento 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>} |
| 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. O objeto JSON deve conter as seguintes propriedades: * invoiceId: O 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. | |
| "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 uso avaliado diário para os conjuntos de atributos "completo" ou "básico", consulte as informações a seguir.
| 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 |
| Tipo de Medidor | 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 |
| 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 mover da v1 para a API v2.
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 mudaram. Por exemplo, 1,00 agora é 100.
Código de exemplo
Para saber mais, consulte Exemplos de API do Partner Center: Obter dados de reconhecimento de faturamento.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários