{"meta":{"title":"REST API を使用した使用状況レポート作成の自動化","intro":"REST API を使用して有料機能の使用に関するレポート作成を自動化する方法について説明します。","product":"課金と支払い","breadcrumbs":[{"href":"/ja/billing","title":"課金と支払い"},{"href":"/ja/billing/tutorials","title":"チュートリアル"},{"href":"/ja/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 を使用して](/ja/rest/using-the-rest-api)」を参照してください。\n\n* ```\n          personal access token (classic)を使用して認証します。 課金の使用状況エンドポイントは、 fine-grained personal access tokensをサポートしていません。\n  ```\n\nレポートのニーズに応じて、API から取得した使用状況データを格納および分析できる内部システム (スプレッドシート、データベース、BI ツールなど) にアクセスすることもできます。\n\n## 手順 1: レポートするレベルを決定する\n\nレポートするアカウント レベルを決定します。 これにより、 **呼び出す REST API エンドポイント** と、レポートに含める内容が決まります。\n\n目標に最も適したレポート レベルを選択します。\n\n| 報告レベル | いつ使用するか |\n| ----- | ------- |\n|       |         |\n\n```\n          **User** | たとえば、個人の使用状況やコストを把握するために、1 つのアカウントのレポートが必要です。 |\n```\n\n|\n**組織** | チーム レベルの監視やチャージバックなど、特定の組織の使用状況とコストを追跡する必要があります。 |\n|\n**エンタープライズ** | 財務レポートやコスト センター レポートなど、複数の組織に対して一元的なビューが必要です。 |\n\nレポート レベルを選択したら、次の手順で対応するエンドポイントを使用して使用状況データを取得し、自動レポートを作成します。\n\n## 手順 2: 有料製品の使用状況データを取得する\n\nレポートするレベルを決定したら、REST API を使用して有料 GitHub 製品の使用状況データを取得します。 すべてのエンドポイントについては、 [課金の使用状況](/ja/rest/billing/usage) を参照してください。\n\n```\n          GitHub には、次の 2 種類の課金使用状況データが用意されています。\n```\n\n\\*\n**使用状況の概要** – すべての有料製品の使用状況とコストデータの集計。\n\\*\n**Premium 要求の使用量** – クォータや超過分の使用量など、Premium 要求の詳細な使用状況と課金データ。\n\nほとんどのレポートシナリオでは、 **使用状況の概要** から始めて全体的な使用状況と支出を把握し、Premium 要求の使用量に関するより深い分析情報が必要な場合は、Premium 要求の使用状況データを使用します。\n\n### 使用状況の概要を取得する\n\n手順 1 で選択したレポート レベルに対応する使用状況の概要エンドポイントを使用します。\n\nたとえば、企業の使用状況の概要を取得するには、次の要求を行います。\n\n`/enterprises/{enterprise}/settings/billing/usage/summary`\n\nこのエンドポイントに対する要求を認証する必要があります。\n\n```\n          **curl の使用例**\n```\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```\n          `ENTERPRISE`をエンタープライズ スラッグに置き換え、`GITHUB_TOKEN`環境変数を必要な課金アクセス許可を持つpersonal access tokenに設定します。\n\n          **を使用した例 GitHub CLI**\n```\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### Premium 要求の使用状況を取得する\n\nPremium 要求の使用量について具体的に報告する必要がある場合は、同じアカウント レベルで `premium_request/usage` エンドポイントを使用します。 このエンドポイントは、含まれている使用量、請求された超過分、残りのクォータなどの追加の詳細を提供します。\n\n次の手順では、期間またはコスト センターで使用状況データをフィルター処理して、より対象を絞ったレポートを生成する方法について説明します。\n\n## 手順 3: 期間またはコスト センターで使用状況データをフィルター処理する\n\n既定では、使用状況の概要エンドポイントは **、現在の年**のデータを返します。 より多くの対象となるレポートを生成したり、時間の経過に伴う傾向を分析したりするには、クエリ パラメーターを使用して使用状況データをフィルター処理できます。\n\n### 期間でフィルタする\n\n返される使用状況データを制限するには、次のクエリ パラメーターを 1 つ以上指定します。\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          **数量**。特定の製品と単位の種類の使用量を表します。\n  ```\n* ```\n          **netAmount**。その使用量に対する課金コストを表します\n  ```\n* ```\n          **discountAmount**。含まれているクォータまたは割引の対象となる使用量を表します\n  ```\n\n一般:\n\n* ```\n          **数量**を使用して製品の使用量を把握する\n  ```\n* ```\n          **netAmount** を使用して課金内容を理解する\n  ```\n* ```\n          **discountAmount** を使用して、含まれている使用量または割引された使用量を把握する\n  ```\n\nたとえば、netAmount が少ない数量が多い場合は、ほとんどの使用量が含まれているクォータでカバーされていたことを示している可能性があります。一方、netAmount が時間の経過と共に増加すると、有料の使用量が増加している可能性があります。\n\n製品ごとに、単位の種類 (分、ギガバイト、要求など) を使用して使用状況を報告します。 製品固有のメトリックを計算したり、以前の課金プラットフォームの値を再現したりするには、製品とユニットの種類で使用状況項目をフィルター処理し、結果を集計することが必要になる場合があります。 詳細な例については、次の手順でリンクされているリファレンス ドキュメントを参照してください。\n\n## 手順 6: 製品固有の使用状況メトリックを計算する\n\n場合によっては、使用状況の概要応答から製品固有の使用状況メトリックを計算する必要があります。 これは、特定の製品のカスタム レポートを生成する場合や、レガシ レポートで使用される値を再現する場合に最も重要です。\n\nこれらのメトリックを計算するには、通常、 `product` と `unitType`で使用状況アイテムをフィルター処理し、 `quantity`、 `netAmount`、 `discountAmount`などのフィールドを集計します。\n\n詳細な例と製品固有の計算については、 [課金とライセンスの概要](/ja/billing/reference/previous-billing-platform-endpoints) を参照してください。"}