{"meta":{"title":"REST API를 사용하여 사용 보고 자동화","intro":"REST API를 사용하여 유료 기능 사용에 대한 보고를 자동화하는 방법을 알아보세요.","product":"청구 및 결제","breadcrumbs":[{"href":"/ko/enterprise-cloud@latest/billing","title":"청구 및 결제"},{"href":"/ko/enterprise-cloud@latest/billing/tutorials","title":"자습서"},{"href":"/ko/enterprise-cloud@latest/billing/tutorials/automate-usage-reporting","title":"사용 보고 자동화하기"}],"documentType":"article"},"body":"# REST API를 사용하여 사용 보고 자동화\n\nREST API를 사용하여 유료 기능 사용에 대한 보고를 자동화하는 방법을 알아보세요.\n\n요금제 청구로 전환한 후 내부 보고 시스템의 유료 GitHub 기능에 대한 사용량 및 비용을 자동으로 추적할 수 있습니다. 예를 들어 시간 경과에 따른 지출을 모니터링하거나, 청구서를 조정하거나, 사용량 현황 데이터를 재무 또는 BI 도구에 공급할 수 있습니다.\n\n이 자습서에서는 REST API를 사용하여 청구 사용량 현황 데이터를 검색하고, 기간 또는 비용 센터를 통해 필터링하고, 사용자, 조직 또는 엔터프라이즈 수준에서 되풀이 보고서를 자동화하는 방법을 알아봅니다. 또한 원시 사용량 현황 데이터를 의미 있는 비용 인사이트로 전환할 수 있도록 응답의 주요 필드를 해석하는 방법을 알아봅니다.\n\n## 필수 조건\n\n이 자습서를 시작하기 전에 다음을 확인합니다.\n\n* 보고하려는 수준에서 청구 데이터에 액세스할 수 있습니다.\n  * 사용자 수준 보고서: 계정 소유자\n  * 조직 수준 보고서: 조직 소유자 또는 청구 관리자\n  * 엔터프라이즈 수준 보고서: 엔터프라이즈 관리자 또는 청구 관리자\n\n* REST API에 대한 인증된 요청을 만드는 데 익숙합니다. 소개는 [REST API 사용](/ko/enterprise-cloud@latest/rest/using-the-rest-api)을(를) 참조하세요.\n\n* personal access token (classic)를 사용하여 인증합니다. 청구 사용량 엔드포인트는 fine-grained personal access tokens을(를) 지원하지 않습니다. 엔터프라이즈급 보고의 경우 대신 GitHub App로 인증할 수 있습니다.\n  [\n  GitHub App로 인증하기](#authenticating-with-a-github-app)를 참조하세요.\n\n보고 요구 사항에 따라 API에서 검색된 사용량 현황 데이터를 저장하고 분석할 수 있는 내부 시스템(예: 스프레드시트, 데이터베이스 또는 BI 도구)에 액세스할 수도 있습니다.\n\n## GitHub App를 사용하여 인증하기\n\n엔터프라이즈급 보고의 경우 GitHub App 대신 personal access token로 인증할 수 있습니다. 그러면 자동화는 개별 엔터프라이즈 소유자 또는 청구 관리자에 속한 토큰에 의존하지 않으므로 누군가가 역할을 변경하거나 엔터프라이즈를 떠날 때 보고서가 계속 실행됩니다.\n\n엔터프라이즈 소유자는 다음 두 가지 액세스 수준 중 하나에서 앱에 엔터프라이즈 청구 권한을 부여할 수 있습니다.\n\n* **읽기**: 앱은 사용 보고서, 예산 및 비용 센터를 검색할 수 있습니다. 이 자습서의 보고에 필요한 액세스 권한입니다.\n* **읽기 및 쓰기**: 앱은 예산 및 비용 센터를 만들고, 업데이트하고, 삭제하고, 비용 센터에서 리소스를 추가하거나 제거할 수 있습니다.\n\n앱에서 사용량을 보고하려면 다음을 수행합니다.\n\n1. 엔터프라이즈 청구 권한을 요청하는 GitHub App를 등록합니다.\n   [GitHub 앱 등록](/ko/enterprise-cloud@latest/apps/creating-github-apps/registering-a-github-app/registering-a-github-app)을(를) 참조하세요.\n2. 엔터프라이즈 소유자에게 엔터프라이즈에 앱을 설치하도록 요청합니다.\n   [엔터프라이즈에 GitHub 앱 설치](/ko/enterprise-cloud@latest/apps/using-github-apps/installing-a-github-app-on-your-enterprise)을(를) 참조하세요.\n3. 엔터프라이즈 설치에 대한 설치 액세스 토큰을 생성합니다.\n   [GitHub 앱에 대한 설치 액세스 토큰 생성](/ko/enterprise-cloud@latest/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app)을(를) 참조하세요.\n4. 요청의 `Authorization` 헤더에 personal access token 대신 설치 액세스 토큰을 보내세요.\n\n설치 액세스 토큰은 1시간 후에 만료되므로 자동화는 실행되거나 현재 토큰이 만료 될 때마다 새 토큰을 생성해야 합니다.\n\n앱이 각 권한으로 호출할 수 있는 엔드포인트는 [GitHub 앱에 필요한 권한](/ko/enterprise-cloud@latest/rest/authentication/permissions-required-for-github-apps)을 참조하세요.\n\n## 1단계: 보고할 수준 결정\n\n보고할 계정 수준을 결정합니다. 그러면 **어떤 REST API 엔드포인트를 호출할지** , 보고서에 포함할 엔드포인트가 결정됩니다.\n\n목표와 가장 일치하는 보고 수준을 선택합니다.\n\n| 보고 수준    | 사용 시기                                             |\n| -------- | ------------------------------------------------- |\n| **User** | 예를 들어 단일 계정에 대한 보고서를 사용하여 개인 사용량 및 비용을 이해하려고 합니다. |\n| **조직**   | 특정 조직의 사용량 및 비용(예: 팀 수준 모니터링 또는 차지백)을 추적하려고 합니다.  |\n| **기업**   | 재무 보고 또는 비용 센터 보고와 같이 여러 조직에서 중앙 집중식 보기를 원합니다.    |\n\n보고 수준을 선택한 후에는 다음 단계에서 해당 엔드포인트를 사용하여 사용량 현황 데이터를 검색하고 자동화된 보고서를 작성합니다.\n\n## 2단계: 유료 제품의 사용량 현황 데이터 검색\n\n보고할 수준을 결정한 후 REST API를 사용하여 유료 GitHub 제품의 사용량 현황 데이터를 검색합니다. 모든 엔드포인트는 [청구 사용량](/ko/enterprise-cloud@latest/rest/billing/usage)을 참조하세요.\n\nGitHub 에서는 두 가지 유형의 청구 사용량 현황 데이터를 제공합니다.\n\n* **사용량 요약** – 모든 유료 제품에 대한 집계된 사용량 및 비용 데이터입니다.\n* **AI credits 사용량** – 포함된 풀 사용량과 추가 사용 요금을 포함한 AI credits의 자세한 사용량 및 청구 내역.\n\n대부분의 보고 시나리오에서는 **사용량 요약**으로 시작하여 전체 사용량 및 지출을 파악한 다음, 소비에 대한 심층적인 인사이트 AI credits 가 필요할 때 사용량 현황 데이터를 사용합니다Copilot.\n\n### 사용 요약 검색\n\n1단계에서 선택한 보고 수준에 해당하는 사용 요약 엔드포인트를 사용합니다.\n\n예를 들어 엔터프라이즈에 대한 사용 요약을 검색하려면 다음을 요청합니다.\n\n`/enterprises/{enterprise}/settings/billing/usage/summary`\n\n이 엔드포인트에 대한 요청을 인증해야 합니다.\n\n**curl을 사용하는 예제**\n\n```bash\ncurl -L \\\n  -H \"Authorization: Bearer $GITHUB_TOKEN\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  https://api.github.com/enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\n`ENTERPRISE` 엔터프라이즈 슬러그로 바꾸고 환경 변수를 `GITHUB_TOKEN`personal access token 필요한 청구 권한으로 설정합니다. 또는 엔터프라이즈 청구 권한이 있는 `GITHUB_TOKEN`의 설치 액세스 토큰으로 GitHub App를 설정합니다.\n\n**다음을 사용하는 예제 GitHub CLI**\n\n```bash\ngh api \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /enterprises/ENTERPRISE/settings/billing/usage/summary\n```\n\n이 엔드포인트는 기본적으로 현재 연도의 모든 유료 제품에 대해 집계된 사용량 현황 데이터를 반환합니다. 각 항목에는 제품, 단위 유형, 사용된 수량 및 청구 금액과 같은 정보가 포함됩니다.\n\n동일한 방법을 사용하여 해당 계정 수준에 해당하는 엔드포인트를 호출하여 조직 또는 사용자의 사용 요약을 검색할 수 있습니다.\n\n### AI credits 사용량 가져오기\n\n소비에 대해 Copilot 구체적으로 보고해야 하는 경우 동일한 계정 수준에 대해 AI 사용량 엔드포인트를 사용합니다. 이 엔드포인트는 포함된 풀 사용량, 청구된 추가 사용량 및 모델별 사용량과 같은 추가 세부 정보를 제공합니다.\n\n## 3단계: 기간 또는 비용 센터를 통해 사용량 현황 데이터 필터링\n\n기본적으로 사용 요약 엔드포인트는 **현재 연도**의 데이터를 반환합니다. 시간이 지남에 따라 더 많은 대상 보고서를 생성하거나 추세를 분석하려면 쿼리 매개 변수를 사용하여 사용량 현황 데이터를 필터링할 수 있습니다.\n\n### 기간별로 필터링\n\n다음 쿼리 매개 변수 중 하나 이상을 지정하여 반환되는 사용량 현황 데이터를 제한할 수 있습니다.\n\n* `year`\n* `month`\n* `day`\n* `hour`\n\n예를 들어 특정 월의 사용 데이터를 검색하려면 요청에 `year` 및 `month` 매개 변수를 포함하세요.\n\n```http\nGET /enterprises/{enterprise}/settings/billing/usage/summary?year=2024&month=12\n```\n\n기간별 필터링은 다음을 수행하려는 경우에 유용합니다.\n\n* 월별 또는 일별 사용 보고서 생성\n* 새 기능 사용과 같은 변경 전후 사용량 비교\n* 특정 청구 기간에 대한 송장으로 사용량 조정\n\n### 비용 센터별로 필터링(엔터프라이즈 전용)\n\n엔터프라이즈 수준의 사용량 데이터를 검색하는 경우, `cost_center_id` 쿼리 매개 변수를 통해 비용 센터로 결과를 필터링할 수도 있습니다.\n\n비용 센터를 통해 필터링하면 다음을 수행할 수 있습니다.\n\n* 특정 팀 또는 사업부에 대한 특성 사용량 및 비용\n* 재무 또는 리더십 관련자를 위한 비용 센터별 보고서 생성\n\n비용 센터 필터링은 엔터프라이즈 사용 요약 엔드포인트에만 사용할 수 있습니다.\n\n다음 단계에서는 이러한 API 호출을 자동화하여 되풀이 사용 보고서를 생성하는 방법을 알아봅니다.\n\n## 4단계: 되풀이 사용 보고서 자동화\n\n수집하려는 사용량 현황 데이터와 필터링 방법을 확인한 후에는 되풀이 일정에 따라 동일한 API 요청을 실행하여 보고를 자동화할 수 있습니다.\n\n일반적인 자동화 패턴은 다음과 같습니다.\n\n* 예약된 API 요청(예: 매일 또는 매월)을 실행하여 사용량 현황 데이터 수집\n* 데이터베이스, 스프레드시트 또는 BI 도구와 같은 내부 시스템에 결과 저장\n* 데이터를 사용하여 추세를 모니터링하거나, 사용량 변경을 검색하거나, 비용 검토를 지원합니다.\n\n보고서를 자동화할 때 일관성이 중요합니다. 사용량 추세가 시간에 따라 비교할 수 있도록 매번 동일한 보고 수준, 필터 및 시간 범위를 사용합니다.\n\n예를 들어 다음이 가능할 수도 있습니다.\n\n* 월별 엔터프라이즈 수준 사용량 요약을 실행하여 전체 지출 추적\n* 비용 센터별로 내부 차지백 또는 쇼백에 대한 보고서를 생성합니다.\n* 새 유료 기능을 사용하도록 설정한 후 사용량 증가 모니터링\n\n다음 단계에서는 원시 데이터를 의미 있는 인사이트로 전환할 수 있도록 API에서 반환된 사용량 및 비용 필드를 해석하는 방법을 알아봅니다.\n\n## 5단계: API 응답에서 사용량 및 비용 필드 해석\n\n사용량 요약 응답에는 **사용량** 및 **비용** 정보가 모두 포함됩니다. 이러한 필드가 서로 어떻게 관련되는지 이해하면 지출, 포함된 사용량 및 청구된 초과분 해석에 도움이 됩니다.\n\n각 사용 항목에는 다음이 포함됩니다.\n\n* 특정 제품 및 단위 유형에 대한 사용량을 나타내는 **수량**입니다.\n* 해당 사용량에 대한 청구 비용을 나타내는 **netAmount**\n* 포함된 할당량 또는 할인이 적용되는 사용량을 나타내는 **discountAmount**\n\n일반적으로 다음을 수행합니다.\n\n* **수량을** 사용하여 소비된 제품의 양을 파악합니다.\n* **netAmount**를 사용하여 청구된 내용 이해\n* **discountAmount**를 사용하여 사용량이 포함되거나 할인된 양을 파악합니다.\n\n예를 들어 netAmount가 낮은 높은 수량은 대부분의 사용량이 포함된 할당량에 포함되었음을 나타낼 수 있으며, 시간이 지남에 따라 netAmount가 증가하면 유료 사용량이 증가했음을 나타낼 수 있습니다.\n\n제품별로 다른 단위 유형(예: 분, 기가바이트 또는 요청)을 사용하여 사용량을 보고합니다. 제품별 메트릭을 계산하거나 이전 청구 플랫폼에서 값을 재현하려면 제품 및 단위 유형별로 사용 항목을 필터링하고 결과를 집계해야 할 수 있습니다. 자세한 예제는 다음 단계에서 연결된 참조 설명서에서 사용할 수 있습니다.\n\n## 6단계: 제품별 사용 메트릭 계산\n\n경우에 따라 사용 요약 응답에서 제품별 사용량 메트릭을 계산해야 할 수 있습니다. 이는 특정 제품에 대한 사용자 지정 보고서를 생성하거나 레거시 보고에 사용된 값을 재현하려는 경우에 가장 관련이 있습니다.\n\n이러한 메트릭을 계산하려면 일반적으로 사용량 항목을 `product` 및 `unitType`로 필터링한 다음, `quantity`, `netAmount`, 및 `discountAmount` 같은 필드를 집계합니다.\n\n자세한 예제 및 제품별 계산은 [청구 및 라이선스 소개](/ko/enterprise-cloud@latest/billing/get-started/introduction-to-billing)을 참조하세요."}