Nova API v2 de uso diário do comércio (beta)
Aplica-se a: Partner Center | Partner Center operado pela 21Vianet | Partner Center for Microsoft Cloud for US Government
Use essas APIs para obter novos dados de uso diário faturados e não faturados de forma assíncrona.
Nota
Esta API será preterida 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 diário faturados para períodos de faturamento de setembro de 2022 a 21 de janeiro de 2025.
Ação: Use esta API, mas migre para o v2 GA o mais rápido possível.
Meta: Recuperar itens de linha de uso diário 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 diário não faturados para os períodos de faturamento atual e anterior antes de 21 de janeiro de 2025.
Ação: Use esta API, mas migre para o v2 GA o mais rápido possível.
Meta: recuperar itens de linha de uso diário não faturados para os períodos de faturamento atual e anterior 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 nominal diária faturada e não faturada v2 (GA).
Obrigado pela sua atenção e estamos ansiosos para o seu sucesso contínuo com as nossas APIs de faturação.
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 dados precisos, 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. Ocasionalmente, poderá não ver os dados de utilização diária não faturados mais recentes até que os dados de utilização faturados 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 à medida que nos esforçamos para fornecer as informações mais precisas e oportunas possíveis.
Importante
Os dados de utilização diária nominal não incluem os encargos relativos a 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
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 a chave de manobrista e padrões assíncronos de solicitação-resposta para otimizar nossas APIs de faturamento e reconciliação para entregar 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 (pontos de extremidade da API). Para saber mais, leia as seguintes seções:
Ponto de extremidade de item de linha de uso
Use esta API para acessar itens de linha de consumo faturados ou não faturados. Ele retorna um status HTTP 202 e um cabeçalho de local com a URL, que você deve pesquisar em intervalos regulares até receber um status de sucesso com uma URL de manifesto.
Ponto de extremidade do status da operação
Até receber o status de sucesso, continue pesquisando essa API em um intervalo regular. 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 de manifesto
Este ponto de extremidade fornece uma pasta de armazenamento a partir da qual os dados de faturamento reais 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 descreve as etapas necessárias para baixar dados de reconciliação.
Sequência de ação do usuário
Siga estas etapas para recuperar dados de reconciliação.
Passo 1: Submeter pedido
Envie uma solicitação POST para o ponto de extremidade da API.
Obter itens de linha de uso não faturados
Obtenha itens de linha de uso não faturados para o mês atual ou último do calendário.
Pedido da API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/unbilledusage?fragment={fragment}&period={period}?currencyCode={currencyCode}
Parâmetros de solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| fragment | Query | False | 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. |
| período | Query | True | String | Use "atual" ou "último" para obter o uso para o mês atual ou último do calendário. O valor "last" é o mesmo que "previous" em APIs V1 existentes. |
| currencyCode | Query | True | String | Código da moeda de cobrança do parceiro. |
Parâmetros de solicitação preteridos
A versão mais recente da API não requer os seguintes parâmetros de URI:
| Name | Descrição |
|---|---|
| Provider | N/A. (Ele retorna todo o uso do plano do Azure e é equivalente ao "único" das APIs V1 existentes.) |
| hasPartnerEarnedCredit | N/A. (devolve todos os dados, independentemente da PEC.) |
| Tamanho | N/A. |
| Desvio | N/A. |
| seekOperation | N/A. |
Cabeçalho do pedido
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo do pedido
N/A.
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.
| Name | Descrição |
|---|---|
| 202 Aceito | O pedido é aceite. Consulte a URL do cabeçalho do local da operação para obter o status da solicitação. |
Obter itens de linha de uso faturados
Obtenha itens de linha de uso classificados faturados para o período de faturamento fechado.
Pedido da API
POST https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billedusage/invoices/{invoiceId}?fragment={fragment}
Parâmetros de solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| invoiceId | Caminho | True | String | O número da fatura do Partner Center. |
| Fragment | Query | False | 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 preteridos
A versão mais recente da API não requer os seguintes parâmetros de URI:
| Name | Descrição |
|---|---|
| Provider | N/A. (Ele retorna todo o uso do plano do Azure e é equivalente ao "único" das APIs V1 existentes.) |
| hasPartnerEarnedCredit | N/A. (devolve todos os dados, independentemente da PEC.) |
| Tamanho | N/A. |
| Desvio | N/A. |
| seekOperation | N/A. |
Cabeçalho do pedido
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo do pedido
N/A.
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 Accepted". Com base na solicitação, a API pode retornar outro status padrão.
| Name | Descrição |
|---|---|
| 202 Aceito | O pedido é aceite. Verifique o status da solicitação pesquisando a URL do cabeçalho do local da operação. |
Etapa 2: Verificar o status da solicitação
Aguarde um HTTP 200 com um status de terminal de bem-sucedido ou falhado. A URL do manifesto é o "resourceLocation" no status de sucesso.
Obter o status da operação
Obtém o status de uma solicitação de dados de reconciliação.
Pedido da API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4448-83b4-1e63ab1d3640
Parâmetros de solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| operationId | Caminho | True | String | O ID da operação. |
Cabeçalho do pedido
Consulte a lista de cabeçalhos de solicitação para a API neste artigo.
Corpo do pedido
N/A.
Estado da resposta
Além do status HTTP padrão neste artigo, a API pode retornar esse status HTTP:
| Name | Descrição |
|---|---|
| 410 Desaparecido | Cada link de operação fica ativo por uma quantidade especificada de tempo controlado pelo servidor. Decorrido o tempo, o cliente deverá submeter um novo pedido. |
Carga útil de resposta
A carga útil de resposta da API retorna os seguintes atributos:
| Nome | Opcional | Description |
|---|---|---|
| createdDateTime | false | Tempo de solicitação. |
| lastActionDateTime | false | Hora de alteração de status. |
| resourceLocation | verdadeiro | O URI de carga útil do manifesto. |
| status | false | Valores e ações possíveis. |
| Value | 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". |
| em execução | 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 útil do manifesto usando o URI especificado em resourceLocation. |
| com falhas | Estado terminal, que indica falha permanente. Reinicie a operação. |
Para o atributo de erro:
| Nome | Opcional | Description |
|---|---|---|
| error | verdadeiro | Detalhes do erro fornecidos no formato json se o status da operação falhar. |
| Nome | Opcional | Description |
|---|---|---|
| mensagem | false | Descreve o erro em detalhes |
| code | false | Indica o tipo de erro que ocorreu |
Pedido da API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingoperations/06d01983-07bf-4447-83b4-1e83ab1d3640
Resposta da API
A resposta sugere esperar 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"
}
Pedido da API
(10 segundos após o pedido 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 "succeeded" 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 carga útil de manifesto
O chamador faz uma solicitação GET para a URL de manifesto para saber mais sobre onde os dados de reconciliação são armazenados nos blobs do Azure.
Obter o manifesto
Recupera o manifesto com informações sobre o local de armazenamento do Azure dos dados de reconciliação.
Pedido da API
GET https://ep-billingreconservice-prod-d5bfczcnfvbqbdhx.z01.azurefd.net/v1/billingmanifests/{manifestId}
Parâmetros de solicitação
| Nome | In | Obrigatório | Tipo | Descrição |
|---|---|---|---|---|
| manifestId | Caminho | True | String | A ID do manifesto. |
Cabeçalho do pedido
Consulte a [lista de cabeçalhos de solicitação para a API] neste artigo.
Corpo do pedido
N/A.
Estado da resposta
Além do status HTTP padrão, a API pode retornar esse status HTTP:
| Name | Descrição |
|---|---|
| 410 Desaparecido | Cada link de manifesto fica ativo por uma quantidade especificada de tempo controlado pelo servidor. Decorrido o tempo, o cliente deverá submeter um novo pedido. |
Carga útil de resposta
A resposta da API retorna os seguintes atributos:
| Name | Descrição |
|---|---|
| Versão | A versão do esquema de manifesto. |
| dataFormat | O formato de arquivo de dados de faturamento. Valores possíveis compactadosJSONLines: 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 | Tempo de criação do arquivo de manifesto. |
| eTag | Versão de dados de 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. |
| Tipo de partição | Esta propriedade divide os dados. Se uma determinada partição tiver mais do que o número suportado, os dados sã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 porque o princípio de particionamento pode mudar. |
| blobContagem | Contagem total de ficheiros para este ID de inquilino parceiro. |
| sizeInBytes | Total de bytes em todos os ficheiros. |
| blobs | Uma matriz JSON de objetos "blob" com os detalhes de todos os arquivos para o ID do locatário parceiro. |
| Objeto Blob | |
| Nome | Nome do 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". |
Amostra de carga útil do manifesto
{
"version": "1",
"dataFormat": "compressedJSONLines",
"utcCretedDateTime": "2022-04-29T22:40:57.1853571Z",
"eTag": "0x5B168C7B6E589D2",
"partnerTenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
"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 blob das propriedades "rootFolderSAS" e "rootFolder" 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 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 ao portador da autorização. |
| MS-CorrelationID | False | String | Um rastreador de solicitações internas. Cada solicitação gera um novo rastreador (GUID). |
| MS-CV | False | String | Um rastreador de solicitações internas. |
| MS-RequestID | False | String | O ID de idempotência da solicitação. |
Status de resposta padrão da API
A seguir estão os status HTTP da resposta da API:
| Name | Descrição |
|---|---|
| 400 Pedido Incorreto | Havia dados ausentes ou incorretos. Os detalhes do erro são incluídos no corpo da resposta. |
| 401 Não Autorizado | O chamador não é autenticado e deve autenticar-se 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. |
| 500 Erro de Servidor Interno | A API ou uma de suas dependências não consegue atender à solicitação. Tente novamente mais tarde. |
| 404 Não Encontrado | Recurso não disponível com parâmetros de entrada. |
| 410 Desaparecido | O link de manifesto expirou ou expirou. Envie uma nova solicitação. |
Atributos de dados de uso
A resposta da API de uso faturada ou não faturada com o parâmetro de solicitação "completo" ou "básico" retorna os seguintes atributos:
| Atributo | "Completo" | "básico" |
|---|---|---|
| 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 |