YouTube Reporting API - System-Managed Reports

YouTube erstellt automatisch eine Reihe von vom System verwalteten Berichten zu Werbeeinnahmen für Rechteinhaber, die Zugriff auf die entsprechenden Berichte in Creator Studio haben. Über diese Berichte erhalten Nutzer programmatischen Zugriff auf Daten, die auch in manuell herunterladbaren Berichten über das Menü „Berichte“ in YouTube Studio verfügbar sind.

Hinweis: Die API bietet Zugriff auf andere Berichte als Creator Studio, auch wenn die Berichte ähnliche Daten enthalten. API-Berichte können andere Felder und andere Feldnamen als Creator Studio-Berichte enthalten.

Da YouTube automatisch vom System verwaltete Berichte erstellt, unterscheidet sich der Prozess zum Abrufen dieser Berichte von dem für die Bulk-Datenberichte in YouTube Analytics, die über die API verfügbar sind.

Berichte abrufen

In den folgenden Schritten wird erläutert, wie Sie systemverwaltete 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 mithilfe des OAuth 2.0-Protokolls Autorisierungstoken abgerufen werden.

Für Anfragen an die YouTube Reporting API werden die folgenden Autorisierungsbereiche verwendet:

Ebenen
https://www.googleapis.com/auth/yt-analytics.readonly YouTube Analytics-Berichte für deine YouTube-Inhalte abrufen. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität, z. B. die Anzahl der Aufrufe und Bewertungen.
https://www.googleapis.com/auth/yt-analytics-monetary.readonly YouTube Analytics-Finanzberichte für deine YouTube-Inhalte abrufen. Dieser Bereich bietet Zugriff auf Messwerte zur Nutzeraktivität sowie auf Messwerte zum geschätzten Umsatz und zur Anzeigenleistung.

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 an, der mit diesem Job verknüpft ist. Ihre Anwendung benötigt im folgenden Schritt den Attributwert id aus derselben Ressource.

Im Dokument Berichte sind die verfügbaren Berichte, die zugehörigen 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 von Berichten abzurufen, die für den Job erstellt wurden. 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:

  • Geben Sie mit dem Parameter createdAfter an, dass die API nur Berichte zurückgeben soll, die nach einer bestimmten Zeit erstellt wurden. Mit diesem Parameter können Sie dafür sorgen, 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. Während sich der Parameter createdAfter auf den Zeitpunkt der Berichterstellung bezieht, bezieht sich dieses Datum 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 dem angegebenen Datum entsprechen oder danach liegen. Wie der Parameter startTimeBefore entspricht dieser Parameterwert den Daten im Bericht und nicht dem Zeitpunkt, zu dem der Bericht erstellt wurde.

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

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

  • Die createTime-Eigenschaft der Ressource gibt das Datum und die Uhrzeit der Berichterstellung an. Ihre App sollte diesen Wert speichern und verwenden, um festzustellen, ob sich zuvor heruntergeladene Berichte geändert haben.

Schritt 4: Bericht herunterladen

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

Berichte verarbeiten

Best Practices

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

  • Anhand der Kopfzeile eines Berichts können Sie die Reihenfolge der Berichtsspalten festlegen. Beispielsweise sollten Sie nicht davon ausgehen, dass Aufrufe der erste Messwert sein wird, der in einem Bericht zurückgegeben wird, nur weil er der erste in einer Berichtsbeschreibung ist. Verwenden Sie stattdessen die Kopfzeile des Berichts, um zu ermitteln, welche Spalte diese Daten enthält.

  • Protokollieren Sie die Berichte, die Sie heruntergeladen haben, um zu vermeiden, dass derselbe Bericht mehrfach verarbeitet wird. In der folgenden Liste finden Sie einige Möglichkeiten, dies zu tun.

    • Verwenden Sie beim Aufrufen der Methode reports.list den Parameter createdAfter, um nur Berichte abzurufen, die nach einem bestimmten Datum erstellt wurden. Wenn Sie zum ersten Mal Berichte abrufen, lassen Sie den Parameter createdAfter weg.

      Jedes Mal, wenn Sie Berichte abrufen und erfolgreich verarbeiten, wird der Zeitstempel gespeichert, der dem Datum und der Uhrzeit entspricht, an dem der neueste Bericht erstellt wurde. Aktualisieren Sie anschließend den Wert des Parameters createdAfter bei jedem weiteren Aufruf der reports.list-Methode, damit bei jedem Aufruf der API nur neue Berichte abgerufen werden, einschließlich neuer Berichte mit Backfill-Daten.

      Prüfen Sie vor dem Abrufen eines Berichts, ob die ID des Berichts bereits in Ihrer 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 wie Datum und Uhrzeit der Generierung des Berichts oder startTime und endTime des Berichts speichern, die zusammen den Zeitraum identifizieren, für den der Bericht Daten enthält. Bei Berichten, die Bulk-Daten für YouTube Analytics abrufen, verfügt jeder Job wahrscheinlich über 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, enthalten weniger Berichte.

      Anhand der Berichts-ID können Sie Berichte identifizieren, die Sie noch herunterladen und importieren müssen. Wenn jedoch zwei neue Berichte dieselben Property-Werte startTime und endTime haben, importieren Sie den Bericht nur mit dem neueren createTime-Wert.

Berichtsmerkmale

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

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

  • Berichtsdaten sind nicht sortiert.