Obtenha conjuntos de dados de pequeno custo sob demanda

  • Artigo

Use a API de Detalhes de Custo para obter dados de custo brutos e não agregados que correspondam à sua fatura do Azure. A API é útil quando a sua organização precisa de uma solução de obtenção de dados através de programação. Considere usar a API se quiser 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 contínuas de ingestão de dados e para o download de conjuntos de dados maiores.

Se você quiser obter grandes quantidades de dados exportados regularmente, consulte Recuperar grandes conjuntos de dados de custo recorrentemente com exportações.

Para saber mais sobre os dados em detalhes de custo (anteriormente referidos como detalhes de uso), consulte Dados de detalhes de custo de ingestão.

O relatório Detalhes de Custo só está disponível para clientes com um Enterprise Agreement ou um Contrato de Cliente Microsoft. Se você for um cliente MSDN, pré-pago ou Visual Studio, consulte Obter detalhes de custo para uma assinatura pré-paga.

Permissões

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

Nota

A API de Detalhes de Custo não suporta grupos de gerenciamento para clientes EA ou MCA.

Para obter mais informações, consulte:

Práticas recomendadas da API de detalhes de custo

A Microsoft recomenda as seguintes práticas recomendadas ao usar a API de detalhes de custo.

Agendamento do pedido

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. Se ligar com mais frequência, receberá dados idênticos. Depois de baixar os dados de custo das faturas históricas, as cobranças não mudam, a menos que você seja explicitamente notificado. Recomendamos armazenar em cache seus dados de custo em um armazenamento consultável ao seu lado para evitar chamadas repetidas para dados idênticos.

Fragmente os seus pedidos

Divida suas chamadas em pequenos intervalos de datas para obter arquivos mais gerenciáveis que você pode baixar pela rede. Por exemplo, recomendamos dividir por dia ou por semana se você tiver um arquivo de custo grande 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 fazer várias chamadas para escopos filho para obter arquivos mais gerenciáveis que possam ser baixados. Para obter mais informações sobre os âmbitos do Cost Management, veja Compreender e trabalhar com âmbitos. Depois de baixar os dados, use o Excel para analisar ainda mais os dados com filtros e tabelas dinâmicas.

Se o conjunto de dados tiver mais de 2 GB (ou aproximadamente 2 milhões de linhas) mensalmente, considere usar Exportações como uma solução mais escalável.

Limites de latência e taxa

As chamadas sob demanda para a API são limitadas por tarifa. O tempo que leva para gerar seu arquivo de detalhes de custo está diretamente correlacionado com a quantidade de dados no arquivo. Para entender o tempo esperado antes que o arquivo fique disponível para download, você pode usar o retry-after cabeçalho na resposta da API.

Intervalos de tempo do conjunto de dados suportados

A API de Detalhes de Custo suporta um intervalo de tempo máximo de conjunto de dados de um mês por relatório. Os dados históricos podem ser recuperados até 13 meses antes da data atual. Se você quiser semear um conjunto de dados histórico de 13 meses, recomendamos fazer 13 chamadas em conjuntos de dados de um mês nos últimos 13 meses. Para recuperar dados históricos com mais de 13 meses, use a API REST de exportação.

Exemplo de solicitações de API de detalhes de custo

As solicitações de exemplo a seguir são usadas por clientes da Microsoft para abordar cenários comuns. Os dados devolvidos pelo pedido correspondem à data em que o custo foi recebido pelo sistema de faturação. Poderão incluir custos de várias faturas. É uma API assíncrona. Como tal, você faz uma chamada inicial para solicitar seu relatório e recebe um link de sondagem no cabeçalho da resposta. A partir daí, você pode pesquisar o link fornecido até que o relatório esteja disponível para você.

Use o retry-after cabeçalho na resposta da API para ditar quando sondar a API em seguida. O cabeçalho fornece um tempo mínimo estimado que o relatório leva para ser gerado.

Para saber mais sobre o contrato da API, consulte API de detalhes de custo.

Custo real versus custo amortizado

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

O custo amortizado divide as suas compras de reserva em partes diárias e distribui-as ao longo do período de reserva. Por exemplo, em vez de ver uma compra de 365 $ a 1 de janeiro, verá uma compra de 1,00 $ 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 usando os recursos específicos que utilizaram a reserva. Por exemplo, se a cobrança diária de US$ 1,00 fosse dividida entre duas máquinas virtuais, você veria duas cobranças de US$ 0,50 por dia. Se parte da reserva não for utilizada num dia, verá um custo de 0,50 $ associado à máquina virtual aplicável e o outro custo de 0,50 $ associado ao tipo de custo de UnusedReservation. Os custos de reserva não utilizados são vistos apenas ao visualizar o custo amortizado.

Devido à mudança na forma como os custos são representados, é importante observar que as visualizações de custo real e custo amortizado mostram números totais diferentes. Em geral, o custo total de meses ao longo do tempo para uma compra de reserva diminuirá ao visualizar os custos amortizados. O custo dos meses seguintes a uma reserva de compra aumenta. A amortização está disponível apenas para compras de reserva e não se aplica atualmente a compras no 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 do pedido:

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

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

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

Aqui estão os campos disponíveis que você pode fornecer no corpo da solicitação de relatório.

  • métrica - O tipo de relatório solicitado. Pode ser ActualCost ou AmortizedCost. Não necessário. Se o campo não for especificado, o padrão da API será um relatório ActualCost.
  • timePeriod - O intervalo de datas solicitado para os seus 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 seus dados. Este parâmetro só é utilizado por clientes do Contrato de Cliente da Microsoft. Além disso, ele só pode ser usado no escopo Perfil de Faturamento ou 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 faturação solicitado para os seus dados. Este parâmetro é usado apenas por clientes do Enterprise Agreement. 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 o pedido foi aceite. Use o cabeçalho para verificar o Location status.

Cabeçalhos de resposta:

Nome Type Formato Description
Localização String A URL para verificar o resultado da operação assíncrona.
Repetir-Depois Número inteiro Int32 O tempo esperado para que seu relatório seja gerado. Aguarde esta duração antes de voltar a votar.

Pesquisa de relatórios e download

Sonde o relatório usando o ponto de extremidade fornecido no location cabeçalho da resposta da API depois de fazer uma solicitação para criar um relatório de Detalhes de Custo. Aqui está um exemplo de solicitação de sondagem.

Solicitação de sondagem de 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/00000000-0000-0000-0000-000000000000/providers/Microsoft.CostManagement/operationResults/00000000-0000-0000-0000-000000000000",
  "name": "00000000-0000-0000-0000-000000000000",
  "status": "Completed",
  "manifest": {
    "manifestVersion": "2022-05-01",
    "dataFormat": "Csv",
    "blobCount": 1,
    "byteCount": 160769,
    "compressData": false,
    "requestContext": {
      "requestScope": "subscriptions/00000000-0000-0000-0000-000000000000",
      "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 principais campos na resposta da API:

  • manifestVersion - A versão do contrato de manifesto usada na resposta. Neste momento, a versão de manifesto permanece a mesma para uma determinada versão da API.
  • dataFormat - CSV é o único formato de arquivo suportado 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. Projete seus pipelines de dados para ser capaz de lidar com arquivos particionados de acordo. O particionamento permite que você possa ingerir conjuntos de dados maiores mais rapidamente no futuro.
  • 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 para a primeira versão. No entanto, a API suportará compressã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 - O 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.

Próximos passos