Automatisieren von Nutzungsberichten mit der REST-API

Nach dem Übergang zur verbrauchsabhängigen Abrechnung können Sie die Nutzung und die Kosten für kostenpflichtige GitHub-Funktionen in Ihren internen Berichtssystemen automatisch nachverfolgen. Beispielsweise möchten Sie die Ausgaben im Laufe der Zeit überwachen, Rechnungen abgleichen oder Nutzungsdaten in Finanz- oder BI-Tools einspeisen.

In diesem Lernprogramm erfahren Sie, wie Sie die REST-API verwenden, um Abrechnungsnutzungsdaten abzurufen, nach Zeitraum oder Kostenstelle zu filtern und wiederkehrende Berichte auf Benutzer-, Organisations- oder Unternehmensebene zu automatisieren. Außerdem erfahren Sie, wie Sie wichtige Felder in der Antwort interpretieren, damit Sie rohe Nutzungsdaten in aussagekräftige Kosteneinblicke umwandeln können.

Voraussetzungen

Bevor Sie mit diesem Lernprogramm beginnen, stellen Sie sicher, dass:

• Sie haben Zugriff auf Abrechnungsdaten auf der Ebene, zu der Sie berichten möchten:

  • Berichte auf Benutzerebene: Kontoinhaber
  • Berichte auf Organisationsebene: Organisationsbesitzer oder Abrechnungsmanager
  • Berichte auf Unternehmensebene: Unternehmensadministrator oder Abrechnungs-Manager

• Sie sind mit der Erstellung authentifizierter Anforderungen an die REST-API vertraut. Eine Einführung findest du unter Verwenden der REST-API.

• Sie führen die Authentifizierung mit einem personal access token (classic) durch. Die Endpunkte für die nutzungsbasierte Abrechnung unterstützen fine-grained personal access tokens nicht.

Je nach Ihren Berichtsanforderungen möchten Sie möglicherweise auch auf ein internes System (z. B. ein Arbeitsblatt, eine Datenbank oder ein BI-Tool) zugreifen, in dem Sie die von der API abgerufenen Nutzungsdaten speichern und analysieren können.

Schritt 1: Entscheiden, über welche Ebene Bericht erstellt werden soll

Entscheiden Sie, über welche Kontoebene Sie berichten möchten. Dadurch wird bestimmt , welcher REST-API-Endpunkt Sie aufrufen und welchen Bericht sie enthalten soll.

Wählen Sie die Berichtsebene aus, die Ihrem Ziel am besten entspricht:

Berichterstellungsebene	Wann man es verwenden sollte

          **Benutzer** | Sie möchten einen Bericht für ein einzelnes Konto erstellen, z. B. um persönliche Nutzung und Kosten zu verstehen. |

| Organisation | Sie möchten nutzungs- und kostenbezogene Kosten für eine bestimmte Organisation nachverfolgen, z. B. für die Überwachung auf Teamebene oder den Rückbuchungsaufwand.You want to track usage and costs for a specific organization, for example for team-level monitoring or chargeback. | | Unternehmen | Sie möchten eine zentralisierte Ansicht in mehreren Organisationen, z. B. für Finanzberichte oder Kostencenterberichte. |

Nachdem Sie eine Berichtsstufe ausgewählt haben, verwenden Sie den entsprechenden Endpunkt im nächsten Schritt, um Nutzungsdaten abzurufen und einen automatisierten Bericht zu erstellen.

Schritt 2: Abrufen von Nutzungsdaten für kostenpflichtige Produkte

Nachdem Sie entschieden haben, auf welcher Ebene berichtet werden soll, verwenden Sie die REST-API, um Nutzungsdaten für kostenpflichtige GitHub Produkte abzurufen. Alle Endpunkte finden Sie unter Nutzungsabrechnung.

GitHub stellt zwei Arten von Abrechnungsnutzungsdaten bereit:

•         **Nutzungszusammenfassungen** – aggregierte Nutzungs- und Kostendaten für alle kostenpflichtigen Produkte.
  

•         **Nutzung von Premium-Anforderungen** – detaillierte Nutzungs- und Abrechnungsdaten für Premium-Anforderungen, einschließlich Kontingente und Überlastungsnutzung.
  

In den meisten Berichterstellungsszenarien beginnen Sie mit einer Nutzungszusammenfassung , um die allgemeine Nutzung und Ausgaben zu verstehen und dann Premium-Anforderungsnutzungsdaten zu verwenden, wenn Sie tiefere Einblicke in den Premium-Anforderungsverbrauch benötigen.

Abrufen einer Verwendungszusammenfassung

Verwenden Sie den Endpunkt für die Verwendungszusammenfassung, der der in Schritt 1 ausgewählten Berichtsebene entspricht.

Um beispielsweise eine Nutzungszusammenfassung für ein Unternehmen abzurufen, stellen Sie eine Anforderung an:

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

Sie müssen Ihre Anforderung für diesen Endpunkt authentifizieren.

          **Beispiel für die Verwendung von 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

Ersetze ENTERPRISE durch den Enterprise Slug und lege die GITHUB_TOKEN Umgebungsvariable auf einen personal access token mit den erforderlichen Berechtigungen für die Rechnungsstellung fest.

          **Beispiel für die Verwendung der GitHub CLI**

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

Dieser Endpunkt gibt aggregierte Nutzungsdaten für alle kostenpflichtigen Produkte für das aktuelle Jahr standardmäßig zurück. Jeder Eintrag enthält Informationen wie Das Produkt, den Einheitentyp, die verwendete Menge und den rechnungsierten Betrag.

Sie können denselben Ansatz verwenden, um Nutzungszusammenfassungen für eine Organisation oder einen Benutzer abzurufen, indem Sie den entsprechenden Endpunkt für diese Kontoebene aufrufen.

Abrufen der Premiumanforderungsnutzungsdaten

Wenn Sie speziell den Premium-Anforderungsverbrauch melden müssen, verwenden Sie den premium_request/usage Endpunkt für die gleiche Kontoebene. Dieser Endpunkt bietet zusätzliche Details wie enthaltene Nutzung, berechnete Überschreitungen und verbleibendes Kontingent.

Im nächsten Schritt erfahren Sie, wie Sie Nutzungsdaten nach Zeitraum oder Kostenstelle filtern, damit Sie gezieltere Berichte erstellen können.

Schritt 3: Filtern von Nutzungsdaten nach Zeitraum oder Kostenstelle

Standardmäßig geben Nutzungszusammenfassungsendpunkte Daten für das aktuelle Jahr zurück. Um gezieltere Berichte zu generieren oder Trends im Laufe der Zeit zu analysieren, können Sie Nutzungsdaten mithilfe von Abfrageparametern filtern.

Nach Zeitraum filtern

Sie können die zurückgegebenen Nutzungsdaten einschränken, indem Sie einen oder mehrere der folgenden Abfrageparameter angeben:

• year
• month
• day
• hour

Wenn Sie z. B. Nutzungsdaten für einen bestimmten Monat abrufen möchten, schließen Sie die Parameter year und month in Ihre Anforderung ein.

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

Die Filterung nach Zeitraum ist nützlich, wenn Sie Folgendes ausführen möchten:

• Generieren monatlicher oder täglicher Nutzungsberichte
• Vergleichen der Verwendung vor und nach einer Änderung, z. B. Aktivieren eines neuen Features
• Abgleichen der Nutzung mit Rechnungen für einen bestimmten Abrechnungszeitraum

Nach Kostenstelle filtern (nur Enterprise)

Wenn Sie Nutzungsdaten auf Unternehmensebene abrufen, können Sie die Ergebnisse auch mithilfe des cost_center_id Abfrageparameters nach Kostenstelle filtern.

Das Filtern nach Kostenstelle ermöglicht Folgendes:

• Nutzung und Kosten bestimmten Teams oder Geschäftseinheiten zuordnen
• Generieren von kostencenterspezifischen Berichten für Finanz- oder Führungsbeteiligte

Die Filterung nach Kostenstellen ist nur für zusammenfassende Endpunkte für die Nutzung im Unternehmen verfügbar.

Im nächsten Schritt erfahren Sie, wie Sie diese API-Aufrufe automatisieren, um wiederkehrende Nutzungsberichte zu generieren.

Schritt 4: Automatisieren von wiederkehrenden Verwendungsberichten

Nachdem Sie die Nutzungsdaten identifiziert haben, die Sie sammeln möchten und wie sie gefiltert werden sollen, können Sie Ihre Berichterstellung automatisieren, indem Sie dieselben API-Anforderungen in einem wiederkehrenden Zeitplan ausführen.

Zu den gängigen Automatisierungsmustern gehören:

• Ausführen geplanter API-Anforderungen (z. B. täglich oder monatlich) zum Sammeln von Nutzungsdaten
• Speichern der Ergebnisse in einem internen System wie einer Datenbank, einer Kalkulationstabelle oder einem BI-Tool
• Verwenden der Daten zum Überwachen von Trends, Erkennen von Nutzungsänderungen oder Supportkostenüberprüfungen

Beim Automatisieren von Berichten ist Konsistenz wichtig. Verwenden Sie jedes Mal die gleichen Berichtsebenen, Filter und Zeitbereiche, sodass Nutzungstrends im Laufe der Zeit vergleichbar sind.

Sie können z. B. Folgendes tun:

• Führen Sie eine monatliche Nutzungszusammenfassung auf Unternehmensebene aus, um die Gesamtausgaben nachzuverfolgen.
• Kostencenterspezifische Berichte für interne Rückbuchungen oder Showbacks erstellen
• Überwachen des Nutzungswachstums nach dem Aktivieren neuer kostenpflichtiger Features

Im nächsten Schritt erfahren Sie, wie Sie die von der API zurückgegebenen Nutzungs- und Kostenfelder interpretieren, damit Sie Rohdaten in aussagekräftige Einblicke umwandeln können.

Schritt 5: Interpretieren von Verwendungs- und Kostenfeldern in der API-Antwort

Die Antwort auf die Verwendungszusammenfassung enthält sowohl Nutzungs - als auch Kosteninformationen . Wenn Sie verstehen, wie diese Felder miteinander in Beziehung stehen, können Sie Ausgaben, inkludierte Nutzung und abgerechnete Überschreitungen interpretieren.

Jedes Verwendungselement enthält:

• Eine Menge, die die Menge der Verwendung für ein bestimmtes Produkt und einen bestimmten Einheitentyp darstellt
• Ein netAmount, der die in Rechnung gestellten Kosten für diese Nutzung darstellt
• Ein discountAmount, der die Nutzung von enthaltenen Kontingenten oder Rabatten darstellt

Im Allgemeinen:

• Verwenden Sie die Menge , um zu verstehen, wie viel eines Produkts verbraucht wurde.
• Verwenden sie netAmount , um zu verstehen, was in Rechnung gestellt wurde.
• Verwenden Sie discountAmount , um zu verstehen, wie viel Nutzung enthalten oder reduziert wurde

Beispielsweise kann eine hohe Menge mit einem niedrigen NetAmount darauf hindeuten, dass die meisten Nutzungen durch Kontingente abgedeckt wurden, während ein steigender Nettoeinsatz im Laufe der Zeit auf eine erhöhte bezahlte Nutzung hindeuten kann.

Verschiedene Produkte melden die Verwendung mit unterschiedlichen Einheitentypen (z. B. Minuten, Gigabyte oder Anforderungen). Um produktspezifische Metriken zu berechnen oder Werte aus der vorherigen Abrechnungsplattform zu reproduzieren, müssen Sie möglicherweise Nutzungselemente nach Produkt- und Einheitstyp filtern und die Ergebnisse aggregieren. Ausführliche Beispiele finden Sie in der Referenzdokumentation, die im nächsten Schritt verknüpft ist.

Schritt 6: Berechnen produktspezifischer Nutzungsmetriken

In einigen Fällen müssen Sie möglicherweise produktspezifische Nutzungsmetriken aus der Zusammenfassungsantwort für die Verwendung berechnen. Dies ist am relevantesten, wenn Sie benutzerdefinierte Berichte für ein bestimmtes Produkt generieren oder Werte reproduzieren möchten, die in älteren Berichten verwendet werden.

Zum Berechnen dieser Metriken filtern Sie in der Regel Verwendungselemente nach product und unitTypeaggregieren dann Felder wie quantity, netAmountund discountAmount.

Ausführliche Beispiele und produktspezifische Berechnungen finden Sie unter Einführung in Abrechnung und Lizenzierung.