YouTube Reporting API - System-Managed Reports

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

YouTube erstellt automatisch eine Reihe von systemverwalteten Berichten zu Werbeeinnahmen für Rechteinhaber, die Zugriff auf die entsprechenden Berichte in Creator Studio haben. Diese Berichte bieten programmatischen Zugriff auf Daten, die auch in manuell heruntergeladenen Berichten im Bereich Berichte in YouTube Studio verfügbar sind.

Hinweis: Über die API erhältst du Zugriff auf andere Berichte als in Creator Studio, auch wenn die Daten ähnliche Daten enthalten. API-Berichte können unterschiedliche Felder haben und auch andere Feldnamen als Creator Studio-Berichte verwenden.

Da YouTube automatisch vom System verwaltete Berichte generiert, unterscheidet sich der Vorgang zum Abrufen dieser Berichte von den Bulk-Datenberichten in YouTube Analytics, die über die API verfügbar sind.

Berichte werden abgerufen

In den folgenden Schritten wird erläutert, wie Sie vom System verwaltete Berichte über die API abrufen.

Schritt 1: Anmeldedaten für die Autorisierung abrufen

Alle Anfragen an die YouTube Reporting API müssen autorisiert werden. Im Autorisierungsleitfaden wird erläutert, wie Sie Autorisierungstokens mit dem OAuth 2.0-Protokoll abrufen.

YouTube Reporting API-Anfragen verwenden die folgenden Autorisierungsbereiche:

Sucher
https://www.googleapis.com/auth/yt-analytics.readonly Sieh dir YouTube Analytics-Berichte für deine YouTube-Inhalte an. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität, wie Anzahl der Aufrufe und Anzahl der Bewertungen.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly Sieh dir die YouTube Analytics-Finanzberichte für deine YouTube-Inhalte an. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität sowie auf geschätzte Umsatz- und Anzeigenleistungsmesswerte.

Schritt 2: Job-ID für den gewünschten Bericht abrufen

Rufen Sie die Methode jobs.list auf, um eine Liste der vom System verwalteten Jobs abzurufen. Legen Sie den Parameter includeSystemManaged auf true fest.

Das Attribut reportTypeId in jeder zurückgegebenen Job-Ressource gibt den Typ des vom System verwalteten Berichts für diesen Job an. Ihre Anwendung benötigt im folgenden Schritt den Attributwert id aus derselben Ressource.

Im Dokument Berichte sind verfügbare Berichte, ihre Berichtstyp-IDs und die darin enthaltenen Felder aufgeführt. Sie können auch die Methode reportTypes.list verwenden, um eine Liste der unterstützten Berichtstypen abzurufen.

Schritt 3: Download-URL des Berichts abrufen

Rufen Sie die Methode jobs.reports.list auf, um eine Liste der für den Job erstellten Berichte abzurufen. Legen Sie in der Anfrage den Parameter jobId auf die Job-ID des Berichts fest, den Sie abrufen möchten.

Sie können die Liste der Berichte mit einem oder allen der folgenden Parameter filtern:

  • Verwenden Sie den Parameter createdAfter, um anzugeben, dass die API nur Berichte zurückgeben soll, die nach einer bestimmten Zeit erstellt wurden. Mit diesem Parameter kann sichergestellt werden, dass die API nur Berichte zurückgibt, die Sie noch nicht verarbeitet haben.

  • Verwenden Sie den Parameter startTimeBefore, um anzugeben, dass die API-Antwort nur Berichte enthalten soll, wenn die frühesten Daten im Bericht vor dem angegebenen Datum liegen. Der Parameter createdAfter bezieht sich auf den Zeitpunkt der Erstellung des Berichts, dieses Datum aber auf die Daten im Bericht.

  • Verwenden Sie den Parameter startTimeAtOrAfter, um anzugeben, dass die API-Antwort nur Berichte enthalten soll, wenn die frühesten Daten im Bericht nach dem angegebenen Datum liegen. Wie der Parameter startTimeBefore entspricht dieser Parameterwert den Daten im Bericht und nicht dem Zeitpunkt der Berichterstellung.

Die API-Antwort enthält eine Liste von Report-Ressourcen für diesen Job. Jede Ressource verweist auf einen Bericht, der Daten für einen eindeutigen Zeitraum enthält.

  • Die Attribute startTime und endTime der Ressource geben den Zeitraum an, den die Daten des Berichts abdecken.
  • Die Eigenschaft downloadUrl der Ressource gibt die URL an, von der der Bericht abgerufen werden kann.

  • Das Attribut createTime der Ressource gibt das Datum und die Uhrzeit der Berichterstellung an. In Ihrer Anwendung sollte dieser Wert gespeichert und verwendet werden, um festzustellen, ob sich zuvor heruntergeladene Berichte geändert haben.

Schritt 4: Bericht herunterladen

Senden Sie eine HTTP-GET-Anfrage an downloadUrl, die Sie in Schritt 4 erhalten haben, um den Bericht abzurufen.

Berichte werden verarbeitet

Best Practices

Für Anwendungen, die die YouTube Reporting API verwenden, gelten immer die folgenden Schritte:

  • Verwenden Sie die Kopfzeile eines Berichts, um die Reihenfolge der Spalten festzulegen. Gehen Sie beispielsweise nicht davon aus, dass Aufrufe der erste Messwert in einem Bericht sind, nur weil dies der erste Messwert in einer Berichtsbeschreibung ist. Verwenden Sie stattdessen die Kopfzeile des Berichts, um festzustellen, welche Spalte diese Daten enthält.

  • Notieren Sie sich die heruntergeladenen Berichte, um zu vermeiden, dass sie mehrmals verarbeitet werden. Die folgende Liste enthält einige Möglichkeiten.

    • Wenn Sie die Methode reports.list aufrufen, verwenden Sie den Parameter createdAfter, um nur Berichte abzurufen, die nach einem bestimmten Datum erstellt wurden. Lassen Sie den Parameter createdAfter weg, wenn Sie Berichte zum ersten Mal abrufen.

      Speichern Sie bei jedem Abrufen und erfolgreichen Verarbeiten von Berichten den Zeitstempel, der dem Datum und der Uhrzeit der Erstellung des neuesten Berichts entspricht. Aktualisieren Sie dann den Wert des Parameters createdAfter bei jedem nachfolgenden Aufruf der Methode reports.list, damit bei jedem Aufruf der API nur neue Berichte, einschließlich neuer Berichte mit Backfill-Daten, abgerufen werden.

      Prüfen Sie vor dem Abrufen eines Berichts, ob die ID des Berichts bereits in der Datenbank aufgeführt ist.

    • Speichern Sie die ID für jeden Bericht, den Sie heruntergeladen und verarbeitet haben. Sie können auch zusätzliche Informationen speichern, z. B. Datum und Uhrzeit der Berichterstellung oder startTime und endTime in den Berichten. Diese enthalten zusammen den Zeitraum, für den der Bericht Daten enthält. Bei Berichten, für die Bulk-Daten für YouTube Analytics abgerufen werden, gibt es für jeden Job wahrscheinlich viele Berichte, da jeder Bericht Daten für einen Zeitraum von 24 Stunden enthält. Vom System verwaltete Jobs, die längere Zeiträume abdecken, haben weniger Berichte.

      Verwenden Sie die Berichts-ID, um Berichte zu identifizieren, die Sie noch herunterladen und importieren müssen. Wenn jedoch zwei neue Berichte dieselben Property-Werte für startTime und endTime haben, importieren Sie den Bericht nur mit dem neueren Wert für createTime.

Berichtseigenschaften

API-Berichte sind versionierte .csv-Dateien (durch Kommas getrennte Werte) mit folgenden Eigenschaften:

  • Jeder Bericht enthält Daten für einen eindeutigen Zeitraum von 00:00 Uhr Pacific Time am Startdatum des Berichts bis 23:59 Uhr Pacific Time am Enddatum des Berichts.

  • Berichtsdaten werden nicht sortiert.