Автоматизация отчетов об использовании с помощью REST API

После перехода на счетчик с учётом биллинга вы можете автоматически отслеживать использование и затраты для платных GitHub функций в ваших внутренних системах отчетности. Например, вы можете отслеживать расходы со временем, сверять счета или передавать данные об использовании в финансовые или BI-инструменты.

В этом учебнике вы узнаете, как использовать REST API для получения данных об использовании биллинга, фильтрации по периоду времени или центру затрат, а также автоматизации повторяющихся отчетов на уровне пользователя, организации или предприятия. Вы также научитесь интерпретировать ключевые поля в ответе, чтобы превратить сырые данные о использовании в значимые оценки стоимости.

Предпосылки

Прежде чем начать этот урок, убедитесь, что:

У вас есть доступ к данным по выставлению счетов на том уровне, на котором вы хотите отчётиться:
- Отчёты на уровне пользователя: держатель аккаунта
- Отчёты на уровне организации: владелец организации или менеджер по биллингу
- Отчёты на уровне предприятия: корпоративный администратор или менеджер по биллингу
Вы знакомы с подачей аутентифицированных запросов в REST API. Общие сведения см. в разделе Использование REST API.
Вы аутентификация с помощью personal access token (classic). Конечные точки использования биллинга не поддерживают fine-grained personal access tokens.

В зависимости от ваших потребностей в отчётности, вам также может понадобиться доступ к внутренней системе (например, к таблице, базе данных или BI-инструменту), где вы сможете хранить и анализировать данные об использовании, полученные из API.

Шаг 1: Определитесь, на каком уровне отчитываться

Определитесь, на каком уровне аккаунта вы хотите сообщить. Это определяет, какой REST API конечный пункт вы будете вызывать и что будет включать ваш отчёт.

Выберите уровень отчётности, который лучше всего соответствует вашей цели:

Уровень отчетности	Когда использовать

          **User** | Вам нужен отчет для одного аккаунта, например, чтобы понять личное использование и затраты. |

| Предприятие | Вам нужно отслеживать использование и затраты для конкретной организации, например, для мониторинга на уровне команды или возврата платежей. | | Предприятие | Вам нужен централизованный взгляд на несколько организаций, например, для финансовой отчетности или отчетности по центру затрат. |

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

Шаг 2: Получить данные об использовании платных продуктов

После того как вы определитесь, на каком уровне отчитываться, используйте REST API для получения данных о использовании платных GitHub. Для всех конечных точек см. АВТОЗАГОЛОВОК.

GitHub предоставляет два типа данных об использовании биллинга:

        **Сводки по использованию** — агрегированные данные о расходах и стоимости для всех платных продуктов.

        **Использование премиум-запросов** — подробные данные об использовании и выставлении счетов для премиум-запросов, включая квоты и перерасход.

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

Получить сводку по использованию

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

Например, чтобы получить сводку по использованию для предприятия, сделайте запрос:

/enterprises/{enterprise}/settings/billing/usage/summary

Вы должны подтвердить свой запрос на этом конечном месте.

          **Пример использования закрутки**

curl -L \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary

Замените ENTERPRISE на корпоративный slug и установите GITHUB_TOKEN переменную среды в personal access token с необходимыми разрешениями для выставления счетов.

          **Пример с использованием GitHub CLI**

gh api \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /enterprises/ENTERPRISE/settings/billing/usage/summary

Эта конечная точка по умолчанию возвращает агрегированные данные о использовании всех платных продуктов за текущий год. Каждая запись содержит информацию, такую как продукт, тип единицы, количество использованного и выставленная сумма.

Вы можете использовать тот же способ для получения сводок об использовании для организации или пользователя, вызвав эквивалентную конечную точку для этого уровня.

Получение использования премиум-запросов

Если нужно отчитываться конкретно по потреблению премиум-запросов, используйте premium_request/usage конечную точку для того же уровня аккаунта. Эта конечная точка предоставляет дополнительные данные, такие как включенное использование, выставленные перерасходы и оставшаяся квота.

На следующем этапе вы научитесь фильтровать данные об использовании по периоду времени или центру затрат, чтобы создавать более целевые отчеты.

Шаг 3: Фильтруйте данные об использовании по периоду времени или центру затрат

По умолчанию сводка по конечным точкам использования возвращает данные за текущий год. Для создания более целенаправленных отчетов или анализа тенденций с течением времени вы можете фильтровать данные об использовании по параметрам запросов.

Фильтр по периоду времени

Вы можете ограничить возвратные данные использования, указав один или несколько из следующих параметров запроса:

year
month
day
hour

Например, чтобы получить данные об использовании за конкретный месяц, включите year параметры и month в запрос:

GET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12

Фильтрация по временному периоду полезна, когда вы хотите:

Генерируйте ежемесячные или ежедневные отчеты об использовании
Сравните использование до и после изменений, например, включение новой функции
Сопоставьте использование с счетами за конкретный расчетный период

Фильтр по центру затрат (только для предприятий)

Если вы получаете данные об использовании на уровне предприятия, вы также можете фильтровать результаты по центру затрат с помощью cost_center_id параметра запроса.

Фильтрация по центру затрат позволяет вам:

Приписывайте использование и затраты конкретным командам или бизнес-единицам
Создавайте отчёты, специфичные для центров затрат, для заинтересованных сторон в финансах или руководстве

Фильтрация центров затрат доступна только для конечных точек сводки корпоративного использования.

На следующем этапе вы узнаете, как автоматизировать эти вызовы API для генерации повторяющихся отчётов об использовании.

Шаг 4: Автоматизируйте регулярные отчеты об использовании

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

Распространённые шаблоны автоматизации включают:

Запуск запланированных запросов API (например, ежедневно или ежемесячно) для сбора данных об использовании
Хранение результатов во внутренней системе, такой как база данных, электронная таблица или инструмент BI
Использование данных для мониторинга тенденций, выявления изменений в использовании или поддержки обзора затрат

При автоматизации отчетов важна последовательность. Используйте один и тот же уровень отчетности, фильтры и временные диапазоны каждый раз, чтобы тенденции использования были сопоставимы с течением времени.

Например, можно:

Запускайте ежемесячный свод по использованию на уровне предприятия для отслеживания общих расходов
Генерируйте отчёты, специфичные для центра затрат, для внутренних чарджбэков или шоубэка
Отслеживайте рост использования после включения новых платных функций

На следующем этапе вы научитесь интерпретировать поля использования и стоимости, возвращаемые API, чтобы превратить сырые данные в значимые инсайты.

Шаг 5: Интерпретировать поля использования и стоимости в ответе API

Ответ по сводке использования включает как информацию об расходе , так и о стоимости . Понимание взаимосвязи этих областей помогает интерпретировать расходы, включенное использование и выставленные перерасходы.

Каждый пункт использования включает:

        **Величина**, которая представляет объём использования для конкретного продукта и типа единицы

        **НеттоСумма**, которая представляет собой выставленную стоимость за это использование

        **Сумма дисконта**, которая представляет собой использование, покрываемое включенными квотами или скидками

Вообще:

Используйте количество данных, чтобы понять, сколько продукта было потреблено
Используйте netAmount , чтобы понять, что было выставлено
Используйте discountAmount , чтобы узнать, сколько использования было включено или со скидкой

Например, высокая величина с низкой чистой суммой может указывать на то, что большая часть использования была покрыта включенными квотами, а рост чистой суммы со временем может указывать на увеличение платного использования.

Разные продукты сообщают об использовании различных типов единиц (например, минуты, гигабайты или запросы). Чтобы рассчитать метрики, специфичные для продукта, или воспроизвести значения из предыдущей платформы для выставления счетов, возможно, потребуется отфильтровать товары по типу продукта и единицы единиц и агрегировать результаты. Подробные примеры доступны в справочной документации, приведённой на следующем этапе.

Шаг 6: Рассчитайте специфичные показатели использования продукта

В некоторых случаях может понадобиться рассчитывать метрики использования по продукту на основе ответа на сводку по использованию. Это особенно актуально, если вы хотите генерировать пользовательские отчёты для конкретного продукта или воспроизводить значения, используемые в устаревшей отчетности.

Для расчёта этих метрик обычно фильтруют элементы использования по product и unitType, затем агрегируют поля, такие как quantity, netAmount, и discountAmount.

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