REST API를 사용하여 사용 보고 자동화

요금 청구로 전환한 후 내부 보고 시스템에서 유료 GitHub 기능에 대한 사용량 및 비용을 자동으로 추적할 수 있습니다. 예를 들어 시간 경과에 따른 지출을 모니터링하거나, 청구서를 조정하거나, 사용량 현황 데이터를 재무 또는 BI 도구에 공급할 수 있습니다.

이 자습서에서는 REST API를 사용하여 청구 사용량 현황 데이터를 검색하고, 기간 또는 비용 센터를 통해 필터링하고, 사용자, 조직 또는 엔터프라이즈 수준에서 되풀이 보고서를 자동화하는 방법을 알아봅니다. 또한 원시 사용량 현황 데이터를 의미 있는 비용 인사이트로 전환할 수 있도록 응답의 주요 필드를 해석하는 방법을 알아봅니다.

필수 조건

이 자습서를 시작하기 전에 다음을 확인합니다.

보고하려는 수준에서 청구 데이터에 액세스할 수 있습니다.
- 사용자 수준 보고서: 계정 소유자
- 조직 수준 보고서: 조직 소유자 또는 청구 관리자
- 엔터프라이즈 수준 보고서: 엔터프라이즈 관리자 또는 청구 관리자
REST API에 대한 인증된 요청을 만드는 데 익숙합니다. 소개는 REST API 사용을(를) 참조하세요.
personal access token (classic)을(를) 사용하여 인증합니다. 청구 사용량 엔드포인트는 fine-grained personal access tokens을(를) 지원하지 않습니다.

보고 요구 사항에 따라 API에서 검색된 사용량 현황 데이터를 저장하고 분석할 수 있는 내부 시스템(예: 스프레드시트, 데이터베이스 또는 BI 도구)에 액세스할 수도 있습니다.

1단계: 보고할 수준 결정

보고할 계정 수준을 결정합니다. 그러면 어떤 REST API 엔드포인트를 호출할지 , 보고서에 포함할 엔드포인트가 결정됩니다.

목표와 가장 일치하는 보고 수준을 선택합니다.

보고 수준	사용 시기

          **User** | 예를 들어 단일 계정에 대한 보고서를 사용하여 개인 사용량 및 비용을 이해하려고 합니다. |

| 조직 | 특정 조직의 사용량 및 비용(예: 팀 수준 모니터링 또는 차지백)을 추적하려고 합니다. | | 기업 | 재무 보고 또는 비용 센터 보고와 같이 여러 조직에서 중앙 집중식 보기를 원합니다. |

보고 수준을 선택한 후에는 다음 단계에서 해당 엔드포인트를 사용하여 사용량 현황 데이터를 검색하고 자동화된 보고서를 작성합니다.

2단계: 유료 제품의 사용량 현황 데이터 검색

보고할 수준을 결정한 후 REST API를 사용하여 유료 GitHub 제품에 대한 사용량 현황 데이터를 검색합니다. 모든 엔드포인트는 청구 사용량을 참조하세요.

GitHub 은 다음 두 가지 유형의 청구 사용 현황 데이터를 제공합니다.

        **사용량 요약** – 모든 유료 제품에 대한 집계된 사용량 및 비용 데이터입니다.

        **프리미엄 요청 사용량** – 할당량 및 초과분 사용량을 포함하여 프리미엄 요청에 대한 자세한 사용량 및 청구 데이터입니다.

대부분의 보고 시나리오에서는 사용량 요약 으로 시작하여 전체 사용량 및 지출을 파악한 다음 프리미엄 요청 사용량에 대한 심층적인 인사이트가 필요할 때 프리미엄 요청 사용량 현황 데이터를 사용합니다.

사용 요약 검색

1단계에서 선택한 보고 수준에 해당하는 사용 요약 엔드포인트를 사용합니다.

예를 들어 엔터프라이즈에 대한 사용 요약을 검색하려면 다음을 요청합니다.

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

이 엔드포인트에 대한 요청을 인증해야 합니다.

          **curl을 사용하는 예제**

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`을(를) 엔터프라이즈 슬러그로 바꾸고, 필요한 청구 권한이 있는 환경 변수를 으로 설정합니다`GITHUB_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

일반적으로 다음을 수행합니다.

        **수량을** 사용하여 소비된 제품의 양을 파악합니다.

        **netAmount**를 사용하여 청구된 내용 이해

        **discountAmount**를 사용하여 사용량이 포함되거나 할인된 양을 파악합니다.

예를 들어 netAmount가 낮은 높은 수량은 대부분의 사용량이 포함된 할당량에 포함되었음을 나타낼 수 있으며, 시간이 지남에 따라 netAmount가 증가하면 유료 사용량이 증가했음을 나타낼 수 있습니다.

제품별로 다른 단위 유형(예: 분, 기가바이트 또는 요청)을 사용하여 사용량을 보고합니다. 제품별 메트릭을 계산하거나 이전 청구 플랫폼에서 값을 재현하려면 제품 및 단위 유형별로 사용 항목을 필터링하고 결과를 집계해야 할 수 있습니다. 자세한 예제는 다음 단계에서 연결된 참조 설명서에서 사용할 수 있습니다.

6단계: 제품별 사용 메트릭 계산

경우에 따라 사용 요약 응답에서 제품별 사용량 메트릭을 계산해야 할 수 있습니다. 이는 특정 제품에 대한 사용자 지정 보고서를 생성하거나 레거시 보고에 사용된 값을 재현하려는 경우에 가장 관련이 있습니다.

이러한 메트릭을 계산하려면 일반적으로 사용량 항목을 product 및 unitType로 필터링한 다음, quantity, netAmount, 및 discountAmount 같은 필드를 집계합니다.

자세한 예제 및 제품별 계산은 청구 및 라이선스 소개을 참조하세요.