API de uso diário v2 do novo comércio (beta)
Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center para o Microsoft Cloud for US Government
Use essas APIs para obter dados de uso classificados diários cobrados e não cobrados de novo comércio de forma assíncrona.
Observação
Essa API será descontinuada em breve. Para garantir operações perfeitas, recomendamos migrar para a versão GA. Aqui estão os detalhes que você precisa planejar com antecedência:
Meta: recuperar itens de linha de uso classificado diariamente faturados para períodos de faturamento de setembro de 2022 a 21 de janeiro de 2025.
Ação: use essa API, mas migre para a GA v2 o mais rápido possível.
Meta: recuperar itens de linha de uso avaliado diariamente faturados para períodos de faturamento de setembro de 2022 a partir de 21 de janeiro de 2025.
Ação: use apenas a API v2 GA.
Meta: recuperar itens de linha de uso avaliado diariamente não faturados para os períodos de faturamento atual e anteriores antes de 21 de janeiro de 2025.
Ação: use essa API, mas migre para a GA v2 o mais rápido possível.
Meta: recuperar itens de linha de uso diário não faturado para os períodos de faturamento atual e anteriores 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 classificado diariamente faturado e não cobrado v2 (GA).
Obrigado por sua atenção e esperamos seu sucesso contínuo com nossas APIs 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.
Importante
Os dados de uso diário não incluem as cobranças destes 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
A API assíncrona é um novo método para acessar rapidamente dados de faturamento e reconciliação em partes gerenciáveis. Ele elimina a necessidade de manter uma conexão aberta por horas e percorrer milhões de transações iterativamente.
Usamos chave de manobrista e padrões assíncronos de solicitação-resposta para otimizar nossas APIs de faturamento e reconciliação para fornecer os resultados de forma assíncrona. As respostas da API fornecem um token para acessar os dados de reconciliação com todos os atributos ou um subconjunto.
Você pode baixar os dados de uso de forma assíncrona usando três novas etapas (endpoints de API). Para saber mais, leia as seguintes seções:
Ponto de extremidade do item de linha de uso
Use essa API para acessar itens de linha de consumo faturados ou não faturados. Ele retorna um status HTTP 202 e um cabeçalho de localização com a URL, que você deve sondar em intervalos regulares até receber um status de êxito com uma URL de manifesto.
Ponto de extremidade de status da operação
Até receber o status de sucesso, continue sondando essa API em intervalos regulares. Se os dados solicitados não estiverem disponíveis, a resposta da API incluirá um cabeçalho Retry-After indicando quanto tempo você deve esperar antes de enviar outra solicitação.
Ponto de extremidade do manifesto
Esse ponto de extremidade fornece uma pasta de armazenamento da qual os dados reais de cobrança podem ser baixados. A resposta divide ou particiona os arquivos para otimizar a taxa de transferência e o paralelismo de E/S.
Diagrama de sequência
O diagrama ilustra as etapas necessárias para baixar os dados de reconciliação.
Sequência de ação do usuário
Siga estas etapas para recuperar dados de reconciliação.
Etapa 1: enviar solicitação
Envie uma solicitação POST para o endpoint da API.
Receber itens de linha de uso não faturados
Receber itens de linha de uso não faturados do mês atual ou do último mês.
Solicitação de API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parâmetros da solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| fragmento | Consulta | Falso | String | Escolha "completo" para uma resposta completa ou "básico" para um subconjunto de atributos. O valor padrão é "full". Consulte a lista de atributos neste artigo. |
| period | Consulta | True | String | Use "atual" ou "último" para obter o uso do mês atual ou do último mês. O valor "last" é o mesmo que "previous" nas APIs V1 existentes. |
| currencyCode | Consulta | True | String | Código da moeda de cobrança do parceiro. |
Parâmetros de solicitação obsoletos
A versão mais recente da API não requer os seguintes parâmetros de URI:
| Nome | Descrição |
|---|---|
| Provedor | N/D (Ele retorna todo o uso do plano do Azure e é equivalente ao "único" das APIs V1 existentes.) |
| hasPartnerEarnedCredit | N/D (retorna todos os dados, independentemente do PEC.) |
| Tamanho | N/D |
| Deslocamento | N/D |
| seekOperation | N/D |
Cabeçalho da solicitação
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo da solicitação
N/D
Resposta da API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/811bb8f0-8aca-4807-897c-c15ce50820d6
A API retorna o status HTTP 202. Com base na solicitação, a API pode retornar outro status padrão.
| Nome | Descrição |
|---|---|
| 202 Aceito | O pedido é aceito. Consulte a URL do cabeçalho do local da operação para obter o status da solicitação. |
Receber itens de linha de uso faturados
Receba itens de linha de uso classificado faturados para o período de faturamento fechado.
Solicitação de API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parâmetros da solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| invoiceId | Caminho | True | String | O número da fatura do Partner Center. |
| Fragmento | Consulta | Falso | String | Escolha "completo" para uma resposta completa ou "básico" para um subconjunto de atributos. O valor padrão é "full". Consulte a lista de atributos neste artigo. |
Parâmetros de solicitação obsoletos
A versão mais recente da API não requer os seguintes parâmetros de URI:
| Nome | Descrição |
|---|---|
| Provedor | N/D (Ele retorna todo o uso do plano do Azure e é equivalente ao "único" das APIs V1 existentes.) |
| hasPartnerEarnedCredit | N/D (retorna todos os dados, independentemente do PEC.) |
| Tamanho | N/D |
| Deslocamento | N/D |
| seekOperation | N/D |
Cabeçalho da solicitação
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo da solicitação
N/D
Resposta da API
HTTP/1.1 202 Accepted Operation-Location: https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e83ab1d4640
A API retorna "HTTP 202 aceito". Com base na solicitação, a API pode retornar outro status padrão.
| Nome | Descrição |
|---|---|
| 202 Aceito | O pedido é aceito. Verifique o status da solicitação sondando a URL do cabeçalho operation-location. |
Etapa 2: verificar o status da solicitação
Aguarde um HTTP 200 com um status de terminal de êxito ou falha. A URL do manifesto é o "resourceLocation" no status de êxito.
Obter status da operação
Obtém o status de uma solicitação de dados de reconciliação.
Solicitação de API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parâmetros da solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| operationId | Caminho | True | String | A ID da operação. |
Cabeçalho da solicitação
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo da solicitação
N/D
Status da resposta
Além do status HTTP padrão neste artigo, a API pode retornar este status HTTP:
| Nome | Descrição |
|---|---|
| 410 não existe mais | Cada link de operação fica ativo por um período especificado de tempo controlado pelo servidor. Decorrido o tempo, o cliente deve enviar uma nova solicitação. |
Payload de resposta
A carga de resposta da API retorna os seguintes atributos:
| Nome | Opcional | Descrição |
|---|---|---|
| createdDateTime | false | Solicite tempo. |
| lastActionDateTime | false | Tempo de mudança de status. |
| resourceLocation | true | O URI da carga útil do manifesto. |
| status | false | Valores e ações possíveis. |
| Valor | Ação do cliente |
|---|---|
| não iniciado | Faça outra chamada para verificar o status depois de aguardar o tempo especificado no cabeçalho "Retry-After". |
| executando | Faça outra chamada para verificar o status depois de aguardar o tempo especificado no cabeçalho "Retry-After". |
| bem-sucedido | O estado final de operação, que indica que os dados estão prontos. Recupere a carga do manifesto usando o URI especificado em resourceLocation. |
| falhou | Estado terminal, que indica falha permanente. Reinicie a operação. |
Para atributo de erro:
| Nome | Opcional | Descrição |
|---|---|---|
| erro | true | Detalhes do erro fornecidos no formato json se o status da operação for falha. |
| Nome | Opcional | Descrição |
|---|---|---|
| mensagem | false | Descreve o erro em detalhes |
| código | false | Indica o tipo de erro que ocorreu |
Solicitação de API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Resposta da API
A resposta sugere aguardar 10 segundos antes de tentar novamente ao processar dados.
HTTP/1.1 200 OK
Retry-After: 10
{
"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://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Resposta da API
A API retorna o status "bem-sucedido" e o URI "resourceLocation".
HTTP/1.1 200 OK
Content-Type: application/json
{
"createdDateTime": "2022-06-1T10-01-03.4Z",
"lastActionDateTime": "2022-06-1T10-01-13Z",
"status": "succeeded",
"resourceLocation": "https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/e03e1882-ff59-4c09-882f-74e60b4d7743"
}
Etapa 3: Obter o conteúdo do manifesto
O chamador faz uma solicitação GET para a URL do manifesto para saber mais sobre onde os dados de reconciliação são armazenados nos blobs do Azure.
Obtendo o manifesto
Recupera o manifesto com informações sobre o local de armazenamento do Azure dos dados de reconciliação.
Solicitação de API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parâmetros da solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| manifestId | Caminho | True | String | A ID do manifesto. |
Cabeçalho da solicitação
Consulte a [lista de cabeçalhos de solicitação para a API] neste artigo.
Corpo da solicitação
N/D
Status da resposta
Além do status HTTP padrão, a API pode retornar este status HTTP:
| Nome | Descrição |
|---|---|
| 410 não existe mais | Cada link de manifesto fica ativo por um período especificado de tempo controlado pelo servidor. Decorrido o tempo, o cliente deve enviar uma nova solicitação. |
Payload de resposta
A resposta da API retorna os seguintes atributos:
| Nome | Descrição |
|---|---|
| Versão | A versão do esquema de manifesto. |
| dataFormat | O formato do arquivo de dados de faturamento. Valores possíveis compressedJSONLines: cada blob é um arquivo compactado e os dados no arquivo estão no formato de linhas JSON. Para acessar os dados, descompacte o arquivo. |
| utcCreatedDateTime | Hora de criação do arquivo de manifesto. |
| eTag | Versão de dados do manifesto. Uma alteração nas informações de faturamento gera um novo valor de eTag. |
| partnerTenantId | ID do locatário do parceiro. |
| rootFolder | O diretório raiz do arquivo. |
| rootFolderSAS | O token SAS para acessar o arquivo. |
| partitionType | Essa propriedade divide os dados. Se uma determinada partição tiver mais do que o número suportado, os dados serão divididos em vários arquivos correspondentes ao "partitionValue". Por padrão, o sistema particiona dados 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 em seu código, pois o princípio de particionamento pode mudar. |
| blobCount | Contagem total de arquivos para essa ID de locatário do parceiro. |
| sizeInBytes | Total de bytes em todos os arquivos. |
| blobs | Uma matriz JSON de objetos "blob" com os detalhes de todos os arquivos para a ID do locatário do parceiro. |
| Objeto Blob | |
| Nome | Nome de Blob. |
| sizeInBytes | Tamanho do blob em bytes. |
| partitionValue | A partição que contém o arquivo. Uma partição grande será dividida em vários arquivos, cada um com o mesmo "partitionValue". |
Exemplo de conteúdo do manifesto
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "14f593ad-1edc-474d-aaa0-83abbf9638da",
"rootFolder": "https://{billing.blob.core.windows.net}/{folder_path}",
"rootFolderSAS": "\*\*\*",
"partitionType": "ItemCount",
"blobCount": 3,
"sizeInBytes": 2000,
"blobs": [
{
"name": "{blobName1.json.gz}",
"sizeinBytes": 500,
"partitionValue": "1"
},
{
"name": "{blobName2.json.gz}",
"sizeinBytes": 1000,
"partitionValue": "2"
},
{
"name": "{blobName3.json.gz}",
"sizeinBytes": 500,
"partitionValue": "3"
}
]
}
Etapa 4: Baixar dados de reconciliação de uso do local de armazenamento
Obtenha o token SAS e o local de armazenamento de blobs das propriedades "rootFolderSAS" e "rootFolder" 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 de linhas JSON .
Cabeçalhos de solicitação de API padrão
Todas as APIs aceitam os seguintes cabeçalhos:
| Nome | Obrigatório | Tipo | Descrição |
|---|---|---|---|
| Autorização | True | String | Token de portador de autorização. |
| ms-correlationid | Falso | String | Um rastreador de solicitação interno. Cada solicitação gera um novo rastreador (GUID). |
| MS-CV | Falso | String | Um rastreador de solicitação interno. |
| ms-requestid | Falso | String | A ID de idempotência da solicitação. |
Status de resposta padrão da API
Veja a seguir os status HTTP da resposta da API:
| Nome | Descrição |
|---|---|
| 400 Solicitação Inválida | Havia dados ausentes ou incorretos. Os detalhes do erro estão incluídos no corpo da resposta. |
| 401 Não Autorizado | O chamador não é autenticado e deve se autenticar com o serviço de API do parceiro antes de fazer a primeira chamada. |
| 403 Proibido | O chamador não está autorizado a fazer a solicitação. |
| Erro interno de servidor 500 | A API ou uma de suas dependências não pode atender à solicitação. Tente novamente depois. |
| 404 Não Encontrado | Recurso não disponível com parâmetros de entrada. |
| 410 não existe mais | O link do manifesto expirou ou decorreu Envie uma nova solicitação. |
Atributos de dados de uso
A resposta da API de uso faturado ou não cobrado com o parâmetro de solicitação "full" ou "basic" retorna os seguintes atributos:
| Atributo | "cheio" | "básico" |
|---|---|---|
| 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 |