Поделиться через

Получение небольших наборов данных о затратах по запросу

Use the Cost Details API to get raw, unaggregated cost data that corresponds to your Azure bill. API полезен, если вашей организации требуется программное решение для получения данных. Попробуйте использовать API, если вы хотите проанализировать меньшие наборы данных затрат размером 2 ГБ (2 миллиона строк) или меньше. Однако следует использовать экспорт для текущих рабочих нагрузок приема данных и для скачивания больших наборов данных.

If you want to get large amounts of exported data regularly, see Retrieve large cost datasets recurringly with exports.

To learn more about the data in cost details (formerly referred to as usage details), see Ingest cost details data.

Отчет Сведений о затратах доступен только для клиентов, заключивших Соглашение Enterprise или Клиентское соглашение Microsoft. If you're an MSDN, pay-as-you-go or Visual Studio customer, see Get cost details for a pay-as-you-go subscription.

Разрешения

Чтобы использовать API сведений о затратах, вам потребуются разрешения только для чтения поддерживаемых функций и областей.

Примечание.

API сведений о затратах не поддерживает группы управления для клиентов EA или MCA.

Дополнительные сведения можно найти здесь

Cost Details API best practices

Корпорация Майкрософт рекомендует следующие рекомендации по использованию API сведений о затратах.

Расписание запросов

Если вы хотите получить последние данные о затратах, рекомендуется запрашивать не более одного раза в день. Отчеты обновляются каждые четыре часа. При более частом вызове вы получаете идентичные данные. После скачивания данных о затратах для исторических счетов плата не изменяется, если вам явно не сообщат об этом. Мы рекомендуем кэширование данных о затратах в запрашиваемом хранилище на стороне, чтобы предотвратить повторяющиеся вызовы идентичных данных.

Разделяйте ваши запросы

Разбивайте ваши вызовы на маленькие диапазоны дат, чтобы получить более управляемые файлы, которые можно скачать по сети. For example, we recommend chunking by day or by week if you have a large Azure cost file month-to-month. Если у вас есть области с большим объемом данных о затратах (например, платежный аккаунт), рассмотрите возможность совершения нескольких вызовов к дочерним областям, чтобы получить более управляемые файлы для загрузки. Дополнительные сведения об областях управления затратами см. в статье Общие сведения и работа с областями. После скачивания данных используйте Excel для дальнейшего анализа данных с фильтрами и сводными таблицами.

Если набор данных составляет более 2 ГБ (или примерно 2 миллиона строк) в месяц, рассмотрите возможность использования экспорта в качестве более масштабируемого решения.

Ограничения задержки и скорости

Запросы к API ограничены по частоте. Время, затраченное на создание файла сведений о затратах, напрямую связано с объемом данных в файле. Чтобы понять ожидаемое время, прежде чем файл станет доступным для скачивания, можно использовать заголовок retry-after в ответе API.

Поддерживаемые диапазоны времени набора данных

API сведений о затратах поддерживает максимальный диапазон времени набора данных в месяц в отчете. Исторические данные можно получить до 13 месяцев до текущей даты. If you want to seed a 13-month historical dataset, we recommend placing 13 calls in one month datasets for the past 13 months. Чтобы получить исторические данные, которые старше 13 месяцев, используйте REST API экспорта.

Примеры запросов API сведений о затратах

Примеры запросов, приведенные ниже, используются заказчиками Microsoft для решения распространенных сценариев. Данные, возвращаемые запросом, соответствуют дате получения затрат системой выставления счетов. Это может включать затраты из нескольких счетов-фактур. Это асинхронный АПИ. Таким образом, вы совершаете первоначальный запрос для получения отчета и получаете ссылку для опроса в заголовке ответа. Оттуда можно проверять указанную ссылку до тех пор, пока отчет не станет доступен вам.

Используйте заголовок retry-after в ответе API, чтобы определять момент следующего опроса API. Заголовок предоставляет предполагаемое минимальное время создания отчета.

Дополнительные сведения о контракте API см. в разделе Сведения о затратах API.

Фактические затраты и амортизированные затраты

Чтобы определить, хотите ли вы просмотреть фактический отчет о затратах или амортизированных затратах, измените значение, используемое для поля метрик в тексте первоначального запроса. Доступные значения метрик ActualCost или AmortizedCost.

Amortized cost breaks down your reservation purchases into daily chunks and spreads them over the duration of the reservation term. Например, вместо покупки на $365 1 января вы увидите покупку на $1,00 каждый день с 1 января по 31 декабря. Помимо базовой амортизации, затраты также перераспределяются и соотносятся с определенными ресурсами, использовавшимися в процессе резервирования. For example, if the $1.00 daily charge was split between two virtual machines, you'd see two $0.50 charges for the day. If part of the reservation isn't utilized for the day, you'd see one $0.50 charge associated with the applicable virtual machine and another $0.50 charge with a charge type of UnusedReservation. Неиспользуемые затраты на резервирование отображаются только при просмотре амортизированных затрат.

Из-за изменения представления затрат важно отметить, что фактические затраты и амортизированные представления затрат показывают разные общие числа. In general, the total cost of months over time for a reservation purchase will decrease when viewing amortized costs. The cost of months following a reservation purchase increase. Amortization is available only for reservation purchases and doesn't currently apply to Azure Marketplace purchases.

Первоначальный запрос на создание отчета

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

Текст запроса:

Ниже приведен пример запроса на набор данных ActualCost для указанного диапазона дат.

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

Доступные параметры {scope} для построения правильного URI документированы в Определение идентификатора ресурса для области.

Ниже приведены доступные поля, которые можно указать в тексте запроса отчета.

  • metric - The type of report requested. It can be either ActualCost or AmortizedCost. Необязательно. Если поле не указано, API по умолчанию использует отчет ActualCost.
  • timePeriod — запрошенный диапазон дат для данных. Необязательно. Этот параметр нельзя использовать вместе с параметрами invoiceId или billingPeriod. Если параметр timePeriod, invoiceId или billingPeriod не указан в тексте запроса, API возвращает стоимость текущего месяца.
  • invoiceId - The requested invoice for your data. Этот параметр используется только клиентами клиентского соглашения Майкрософт. Additionally, it can only be used at the Billing Profile or Customer scope. Этот параметр нельзя использовать вместе с параметрами billingPeriod или timePeriod. Если параметр timePeriod, invoiceId или billingPeriod не указан в тексте запроса, API возвращает стоимость текущего месяца.
  • billingPeriod - The requested billing period for your data. Этот параметр используется только клиентами Соглашения Enterprise. Используйте формат YearMonth. Например, 202008. Этот параметр нельзя использовать вместе с параметрами invoiceId или timePeriod. Если параметр timePeriod, invoiceId или billingPeriod не указан в тексте запроса, API возвращает стоимость текущего месяца.

ответ API :

Response Status: 202 – Accepted. Указывает, что запрос был принят. Используйте заголовок Location для проверки состояния.

Заголовки ответа:

Имя Тип Формат Описание
Местоположение Струна URL-адрес для проверки результата асинхронной операции.
Retry-After Целое число Int32 Ожидаемое время создания отчета. Подождите указанное время перед повторным опросом.

Report polling and download

Poll for the report using the endpoint provided in the location header of the API response after you make a request to create a Cost Details report. Ниже приведен пример запроса опроса.

Report polling request:

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

Response Status 200 – Succeeded: указывает, что запрос выполнен успешно.

{
  "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"
}

Ниже приведена сводка по ключевым полям в ответе API:

  • manifestVersion - The version of the manifest contract that is used in the response. В настоящее время версия манифеста остается одинаковой для данной версии API.
  • dataFormat — CSV-файл является единственным поддерживаемым форматом файлов, предоставляемым API в настоящее время.
  • blobCount — представляет количество отдельных объектов данных, присутствующих в наборе данных отчета. Важно отметить, что этот API может предоставить разделенный набор данных из нескольких файлов в ответе на запрос. Спроектируйте конвейеры данных, чтобы иметь возможность обрабатывать секционированные файлы соответствующим образом. Секционирование позволяет загружать и обрабатывать большие наборы данных быстрее в перспективе.
  • byteCount - The total byte count of the report dataset across all partitions.
  • compressData. Для первого выпуска сжатие всегда устанавливается в значение false. ОДНАКО API будет поддерживать сжатие в будущем.
  • requestContext — начальная конфигурация, запрошенная для отчета.
  • blobs - A list of n blob files that together comprise the full report.
    • blobLink — URL-адрес загрузки отдельного BLOB-раздела.
    • byteCount - The byte count of the individual blob partition.
  • validTill — дата, когда отчет больше недоступен.

Связанный контент