Compartilhar via

Obter pequenos conjuntos de dados de custo sob demanda

  • Artigo

Use a API Detalhes de Custo para obter dados de custo brutos e não agregados que correspondem à sua fatura do Azure. A API é útil quando sua organização precisa de uma solução de recuperação de dados programática. Considere usar a API caso queira analisar conjuntos de dados de custo menor de 2 GB (2 milhões de linhas) ou menos. No entanto, você deve usar Exportações para cargas de trabalho de ingestão de dados contínuas e para o download de conjuntos de dados maiores.

Se você quiser exportar grandes volumes de dados regularmente, confira Recuperar conjuntos de dados grandes de custo de modo recorrente com exportações.

Para saber mais sobre os dados nos detalhes de custo (anteriormente chamado de detalhes de uso), consulte Ingerir dados dos detalhes de custo.

O relatório Detalhes do Custo só está disponível para clientes com um Contrato Enterprise ou Contrato de Cliente da Microsoft. Caso seja um cliente MSDN, pagamento conforme o uso ou Visual Studio, consulte Obter detalhes de custo para uma assinatura de pagamento conforme o uso.

Permissões

Para usar a API de Detalhes de Custo, você precisa de permissões somente leitura para recursos e escopos compatíveis.

Observação

A API de detalhes de custo não dá suporte a grupos de gerenciamento para clientes EA ou MCA.

Para obter mais informações, consulte:

Práticas recomendadas da API Detalhes de Custo

A Microsoft recomenda as práticas recomendadas a seguir ao usar a API Detalhes de Custo.

Agenda de solicitação

Se você quiser obter os dados de custo mais recentes, recomendamos que você consulte no máximo uma vez por dia. Os relatórios são atualizados a cada quatro horas. Caso chame com mais frequência, receberá dados idênticos. Após baixar os dados de custo das faturas históricas, os preços não serão alterados, a menos que você seja explicitamente notificado. É recomendável armazenar em cache seus dados de custo em um repositório passível de consulta no seu lado para evitar chamadas repetidas para dados idênticos.

Dividir suas solicitações

Divida suas chamadas em intervalos de datas pequenos para obter arquivos mais gerenciáveis que você pode baixar pela rede. Por exemplo, recomendamos o agrupamento por dia ou por semana se você tiver um arquivo grande de custo do Azure mês a mês. Se você tiver escopos com uma grande quantidade de dados de custo (por exemplo, uma conta de cobrança), considere colocar várias chamadas para escopos filho para obter arquivos mais gerenciáveis que você pode baixar. Para obter mais informações sobre escopos do Gerenciamento de Custos, veja Entender e trabalhar com escopos. Após baixar os dados, use o Excel para analisar ainda mais os dados com filtros e tabelas dinâmicas.

Se seu conjunto de informações tiver mais de 2 GB (ou aproximadamente 2 milhões de linhas) de mês para mês, considere o uso de Exportações como uma solução mais escalonável.

Latência e limites de taxa

As chamadas sob demanda para a API são limitadas. O tempo necessário para gerar o arquivo de detalhes de custo é diretamente proporcional à quantidade de dados no arquivo. Para entender a quantidade de tempo esperada antes que o arquivo fique disponível para download, você pode usar o cabeçalho retry-after na resposta à API.

Intervalos de tempo do conjunto de dados com suporte

A API Detalhes de Custo dá suporte a um intervalo de tempo máximo do conjunto de dados de um mês por relatório. Os dados históricos podem ser recuperados por até 13 meses antes da data atual. Caso queira propagar um conjunto de dados históricos de 13 meses, é recomendável fazer 13 chamadas em conjuntos de dados de um mês nos últimos 13 meses. Para obter dados históricos com mais de 13 meses, utilize a API REST de Exportações.

Exemplos de solicitações da API Detalhes de Custo

As solicitações de exemplo a seguir são usadas pelos clientes da Microsoft para abordar os cenários comuns. Os dados retornados pela solicitação correspondem à data de recebimento do custo pelo sistema de cobrança. Ele pode incluir custos de várias notas fiscais. Esta é uma API assíncrona. Dessa forma, você faz uma chamada inicial para solicitar seu relatório e receber um link de sondagem no cabeçalho de resposta. A partir daí, você pode sondar o link fornecido até que o relatório esteja disponível.

Use o cabeçalho retry-after na resposta à API para ditar quando sondar a API a seguir. O cabeçalho fornece um tempo mínimo estimado que o relatório leva para gerar.

Para saber mais sobre o contrato de API, consulte a API Detalhes de Custo.

Custo real versus custo amortizado

Para controlar se você deseja ver um relatório do custo real ou amortizado, altere o valor usado no campo de métrica no corpo da solicitação inicial. Os valores de métrica disponíveis são ActualCost ou AmortizedCost.

O custo amortizado detalha as compras de sua reserva em partes diárias e as distribui ao longo da duração do termo de reserva. Por exemplo, em vez de ver uma compra de US$ 365 em 1º de janeiro, você verá uma compra de US$ 1 todos os dias de 1º de janeiro a 31 de dezembro. Além da amortização básica, os custos também são realocados e associados ao usar os recursos específicos que usaram a reserva. Por exemplo, se esse preço diário de US$ 1 for dividido entre duas máquinas virtuais, você verá dois preços de US$ 0,50 para o dia. Se parte da reserva não for utilizada para o dia, você verá um preço de US$ 0,50 associado à máquina virtual aplicável e outro preço de US$ 0,50 com um tipo de preço de UnusedReservation. Os custos de reserva não utilizados são vistos apenas na exibição do custo amortizado.

Devido à alteração em como os custos são representados, é importante observar que o custo real e as exibições de custo amortizado exibem números totais diferentes. Em geral, o custo total de meses ao longo do tempo para uma compra de reserva diminuirá ao visualizar custos amortizados. O custo de meses após um aumento de compra de reserva. A amortização só está disponível para compras de reserva e não se aplica atualmente às compras do Azure Marketplace.

Solicitação inicial para criar relatório

POST https://management.azure.com/{scope}/providers/Microsoft.CostManagement/generateCostDetailsReport?api-version=2022-05-01

Corpo da solicitação:

Aqui está uma solicitação de exemplo para um conjunto de dados ActualCost em um intervalo de datas especificado.

{
  "metric": "ActualCost",
  "timePeriod": {
    "start": "2020-03-01",
    "end": "2020-03-15"
  }
}

As opções {scope} disponíveis para criar a URI adequada estão documentadas em Identificar a ID do recurso para um escopo.

Aqui estão os campos disponíveis que podem ser fornecidos no corpo da solicitação de relatório.

  • metric - O tipo de relatório solicitado. Pode ser ActualCost ou AmortizedCost. Não necessário. Se o campo não for especificado, a API será padrão para um relatório ActualCost.
  • timePeriod - O intervalo de datas solicitado para os dados. Não necessário. Esse parâmetro não pode ser usado junto com os parâmetros invoiceId ou billingPeriod. Se um parâmetro timePeriod, invoiceId ou billingPeriod não for fornecido no corpo da solicitação, a API retornará o custo do mês atual.
  • invoiceId - A fatura solicitada para os dados. Esse parâmetro é usado apenas por clientes de Contrato de Cliente da Microsoft. Além disso, ele só pode ser usado no escopo do Perfil de Cobrança ou do Cliente. Esse parâmetro não pode ser usado junto com os parâmetros billingPeriod ou timePeriod. Se um parâmetro timePeriod, invoiceId ou billingPeriod não for fornecido no corpo da solicitação, a API retornará o custo do mês atual.
  • billingPeriod - O período de cobrança solicitado para os dados. Esse parâmetro é usado apenas por clientes do Contrato Enterprise. Use o formato YearMonth. Por exemplo, 202008. Esse parâmetro não pode ser usado junto com os parâmetros invoiceId ou timePeriod. Se um parâmetro timePeriod, invoiceId ou billingPeriod não for fornecido no corpo da solicitação, a API retornará o custo do mês atual.

Resposta da API:

Response Status: 202 – Accepted : indica que a solicitação foi aceita. Use o cabeçalho Location para verificar o status.

Cabeçalhos de resposta:

Nome Type Format Descrição
Location String A URL para verificar o resultado da operação assíncrona.
Retry-After Integer Int32 O tempo esperado para que o relatório seja gerado. Aguarde esse tempo antes de sondar novamente.

Sondagem e download do relatório

Pesquise o relatório usando o ponto de extremidade fornecido no cabeçalho location da resposta à API, após solicitar a criação de um relatório de Detalhes de Custo. Aqui está um exemplo de solicitação de pesquisa.

Solicitação de sondagem do relatório:

GET https://management.azure.com/{scope}/providers/Microsoft.CostManagement/costDetailsOperationStatus/{operationId}?api-version=2022-05-01

Response Status 200 – Succeeded: indica que a solicitação foi bem-sucedida.

{
  "id": "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/providers/Microsoft.CostManagement/operationResults/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "name": "aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e",
      "requestBody": {
        "metric": "ActualCost",
        "timePeriod": {
          "start": "2020-03-01",
          "end": "2020-03-15"
        }
      }
    },
    "blobs": [
      {
        "blobLink": "{downloadLink}",
        "byteCount": 32741
      }
    ]
  },
  "validTill": "2022-05-10T08:08:46.1973252Z"
}

Aqui está um resumo dos campos principais na resposta à API:

  • manifestVersion - A versão do contrato de manifesto que é usada na resposta. Neste momento, a versão do manifesto permanece a mesma para uma determinada versão da API.
  • dataFormat - CSV é o único formato de arquivo com suporte fornecido pela API no momento.
  • blobCount - Representa o número de blobs de dados individuais presentes no conjunto de dados do relatório. É importante observar que essa API pode fornecer um conjunto de dados particionado de mais de um arquivo na resposta. Crie seus pipelines de dados para poder identificar arquivos particionados de acordo. O particionamento permite ingerir conjuntos de dados maiores mais rapidamente.
  • byteCount - a contagem total de bytes do conjunto de dados do relatório em todas as partições.
  • compressData - A compactação sempre é definida como false na primeira versão. No entanto, a API dará suporte à compactação no futuro.
  • requestContext - A configuração inicial solicitada para o relatório.
  • blobs - uma lista de n arquivos de blob que, juntos, compõem o relatório completo.
    • blobLink - A URL de download de uma partição de blob individual.
    • byteCount - A contagem de bytes da partição de blob individual.
  • validTill: a data em que o relatório não está mais acessível.

Conteúdo relacionado