YouTube Data API – Übersicht

Einführung

Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben möchten, die mit YouTube interagieren. Darin werden grundlegende Konzepte von YouTube und der API selbst erläutert. Außerdem wird ein Überblick über die verschiedenen Funktionen gegeben, die von der API unterstützt werden.

Vorbereitung

  1. Sie benötigen ein Google-Konto, um auf die Google API Console zuzugreifen, einen API-Schlüssel anzufordern und Ihre Anwendung zu registrieren.

  2. Erstellen Sie ein Projekt in der Google Developers Console und rufen Sie Autorisierungsanmeldedaten ab, damit Ihre Anwendung API-Anfragen senden kann.

  3. Nachdem Sie Ihr Projekt erstellt haben, müssen Sie dafür sorgen, dass die YouTube Data API einer der Dienste ist, für die Ihre Anwendung registriert ist:

    1. Rufen Sie die API Console auf und wählen Sie das Projekt aus, das Sie gerade registriert haben.
    2. Rufen Sie die Seite Aktivierte APIs auf. Prüfe in der Liste der APIs, ob der Status für die YouTube Data API v3 AN ist.

  4. Falls deine Anwendung eine API-Methode verwendet, die eine Benutzerautorisierung erfordert, solltest du dir das Handbuch zur Authentifizierung durchlesen, um zu erfahren, wie eine OAuth 2.0-Autorisierung implementiert wird.

  5. Wähle eine Client-Bibliothek aus, um deine API-Implementierung zu vereinfachen.

  6. Machen Sie sich mit den grundlegenden Konzepten des JSON-Datenformats (JavaScript Object Notation) vertraut. JSON ist ein gängiges, sprachunabhängiges Datenformat, das eine einfache Textdarstellung beliebiger Datenstrukturen bietet. Weitere Informationen dazu finden Sie unter json.org.

Ressourcen und Ressourcentypen

Eine Ressource ist ein individuelles Datenobjekt mit einer eindeutigen ID. In der Tabelle unten werden die verschiedenen Ressourcentypen beschrieben, mit denen Sie über die API interagieren können.

Ressourcen
activity Enthält Informationen zu einer Aktion, die ein bestimmter Nutzer auf der YouTube-Website ausgeführt hat. Zu den Nutzeraktionen, die in Aktivitätsfeeds gemeldet werden, gehören unter anderem das Bewerten eines Videos, das Teilen eines Videos, das Markieren eines Videos als Favorit und das Posten eines Kanal-Bulletins.
channel Enthält Informationen zu einem einzelnen YouTube-Kanal.
channelBanner Gibt die URL an, die verwendet werden soll, um ein neu hochgeladenes Bild als Bannerbild für einen Kanal festzulegen.
channelSection Enthält Informationen zu einer Reihe von Videos, die ein Kanal ausgewählt hat. Ein Abschnitt kann beispielsweise die neuesten Uploads, die beliebtesten Uploads oder Videos aus einer oder mehreren Playlists eines Kanals enthalten.
guideCategory Gibt eine Kategorie an, die YouTube Kanälen basierend auf ihren Inhalten oder anderen Indikatoren wie der Beliebtheit zuordnet. Mit Guide-Kategorien sollen Kanäle so organisiert werden, dass YouTube-Nutzer die gewünschten Inhalte leichter finden. Kanäle können einer oder mehreren Guide-Kategorien zugeordnet sein, müssen es aber nicht.
i18nLanguage Gibt eine Anwendungssprache an, die von der YouTube-Website unterstützt wird. Die Sprache der Anwendung kann auch als Sprache der Benutzeroberfläche bezeichnet werden.
i18nRegion Gibt einen geografischen Bereich an, den ein YouTube-Nutzer als bevorzugte Inhaltsregion auswählen kann. Die Inhaltsregion kann auch als Inhaltssprache bezeichnet werden.
playlist Stellt eine einzelne YouTube-Playlist dar. Eine Playlist ist eine Sammlung von Videos, die nacheinander abgespielt und mit anderen Nutzern geteilt werden können.
playlistItem Gibt eine Ressource wie ein Video an, die Teil einer Playlist ist. Die Ressource „playlistItem“ enthält auch Details zur Verwendung der enthaltenen Ressource in der Playlist.
search result Enthält Informationen zu einem YouTube-Video, ‑Kanal oder ‑Playlist, die den in einer API-Anfrage angegebenen Suchparametern entsprechen. Ein Suchergebnis verweist zwar auf eine eindeutig identifizierbare Ressource wie ein Video, hat aber keine eigenen persistenten Daten.
subscription Enthält Informationen zu einem YouTube-Nutzerabo. Abonnements benachrichtigen Nutzer, wenn neue Videos auf einem Kanal hinzugefügt werden oder wenn ein anderer Nutzer eine der folgenden Aktionen auf YouTube ausführt: Video hochladen, Video bewerten oder Video kommentieren.
thumbnail Gibt Miniaturansichten an, die einer Ressource zugeordnet sind.
video Stellt ein einzelnes YouTube-Video dar.
videoCategory Gibt eine Kategorie an, die mit hochgeladenen Videos verknüpft wurde oder werden könnte.
watermark Gibt ein Bild an, das während der Wiedergabe von Videos eines bestimmten Kanals angezeigt wird. Der Kanalinhaber kann auch einen Zielkanal angeben, auf den das Bild verweist, sowie Zeitangaben, die bestimmen, wann das Wasserzeichen während der Videowiedergabe erscheint und wie lange es sichtbar ist.

In vielen Fällen enthält eine Ressource Verweise auf andere Ressourcen. Die snippet.resourceId.videoId-Eigenschaft einer playlistItem-Ressource gibt beispielsweise eine Videoressource an, die wiederum vollständige Informationen zum Video enthält. Ein weiteres Beispiel: Ein Suchergebnis enthält entweder das Attribut videoId, playlistId oder channelId, das eine bestimmte Video-, Playlist- oder Kanalressource identifiziert.

Unterstützte Vorgänge

In der folgenden Tabelle sind die gängigsten Methoden aufgeführt, die von der API unterstützt werden. Einige Ressourcen unterstützen auch andere Methoden, die spezifischere Funktionen für diese Ressourcen ausführen. Mit der Methode videos.rate wird beispielsweise eine Nutzerbewertung mit einem Video verknüpft und mit der Methode thumbnails.set wird ein Video-Thumbnail auf YouTube hochgeladen und mit einem Video verknüpft.

Vorgänge
list Ruft (GET) eine Liste mit null oder mehr Ressourcen ab.
insert Erstellt (POST) eine neue Ressource.
update Ändert (PUT) eine vorhandene Ressource, um die Daten in Ihrer Anfrage zu berücksichtigen.
delete Entfernt (DELETE) eine bestimmte Ressource.

Die API unterstützt derzeit Methoden zum Auflisten der einzelnen unterstützten Ressourcentypen sowie Schreibvorgänge für viele Ressourcen.

In der folgenden Tabelle sind die Vorgänge aufgeführt, die für verschiedene Ressourcentypen unterstützt werden. Für Vorgänge, mit denen Ressourcen eingefügt, aktualisiert oder gelöscht werden, ist immer eine Nutzerautorisierung erforderlich. In einigen Fällen unterstützen list-Methoden sowohl autorisierte als auch nicht autorisierte Anfragen. Bei nicht autorisierten Anfragen werden nur öffentliche Daten abgerufen, während bei autorisierten Anfragen auch Informationen über oder private Informationen des aktuell authentifizierten Nutzers abgerufen werden können.

Unterstützte Vorgänge
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Kontingentnutzung

Für die YouTube Data API wird ein Kontingent verwendet, um sicherzustellen, dass Entwickler den Dienst wie vorgesehen nutzen und keine Anwendungen erstellen, die die Dienstqualität unbilligerweise beeinträchtigen oder den Zugriff für andere einschränken. Für alle API-Anfragen, einschließlich ungültiger Anfragen, fallen mindestens 1 Kontingentpunkt an. Das für Ihre Anwendung verfügbare Kontingent finden Sie in der API Console.

Für Projekte,in denen die YouTube Data API aktiviert ist, gilt ein Standardkontingent von 10.000 Einheiten pro Tag. Das ist für die meisten API-Nutzer ausreichend. Das Standardkontingent, das sich ändern kann, hilft uns, Kontingentzuweisungen zu optimieren und unsere Infrastruktur so zu skalieren, dass sie für unsere API-Nutzer von größerem Nutzen ist. Ihren Kontingentverbrauch können Sie in der API Console auf der Seite Kontingente einsehen.

Hinweis:Wenn Sie das Kontingentlimit erreichen, können Sie zusätzliches Kontingent beantragen, indem Sie das Formular für Kontingenterhöhungen für YouTube API-Dienste ausfüllen.

Kontingentnutzung berechnen

Google berechnet die Kontingentnutzung, indem jeder Anfrage Kosten zugewiesen werden. Für verschiedene Arten von Vorgängen fallen unterschiedliche Kontingentkosten an. Beispiel:

  • Ein Lesevorgang, bei dem eine Liste von Ressourcen (Kanäle, Videos, Playlists) abgerufen wird, kostet in der Regel 1 Einheit.
  • Ein Schreibvorgang, mit dem eine Ressource erstellt, aktualisiert oder gelöscht wird, kostet in der Regel 50 Einheiten.
  • Eine Suchanfrage kostet 100 Einheiten.
  • Für das Hochladen eines Videos fallen 100 Einheiten an.

In der Tabelle Kontingentkosten für API-Anfragen sind die Kontingentkosten für jede API-Methode aufgeführt. Anhand dieser Regeln können Sie die Anzahl der Anfragen schätzen, die Ihre Anwendung pro Tag senden kann, ohne Ihr Kontingent zu überschreiten.

Teilressourcen

Die API ermöglicht und erfordert sogar das Abrufen von Teilressourcen, damit Anwendungen das Übertragen, Parsen und Speichern unnötiger Daten vermeiden. Dieser Ansatz sorgt auch dafür, dass die API Netzwerk-, CPU- und Speicherressourcen effizienter nutzt.

Die API unterstützt zwei Anfrageparameter, die in den folgenden Abschnitten erläutert werden. Mit diesen Parametern können Sie die Ressourceneigenschaften angeben, die in API-Antworten enthalten sein sollen.

  • Der Parameter part gibt Gruppen von Attributen an, die für eine Ressource zurückgegeben werden sollen.
  • Mit dem Parameter fields wird die API-Antwort gefiltert, sodass nur bestimmte Eigenschaften innerhalb der angeforderten Ressourcenteile zurückgegeben werden.

part-Parameter verwenden

Der Parameter part ist für jede API-Anfrage erforderlich, mit der eine Ressource abgerufen oder zurückgegeben wird. Mit dem Parameter werden eine oder mehrere Ressourcen-Properties der obersten Ebene (nicht verschachtelt) angegeben, die in eine API-Antwort aufgenommen werden sollen. Eine video-Ressource besteht beispielsweise aus folgenden Teilen:

  • snippet
  • contentDetails
  • fileDetails
  • player
  • processingDetails
  • recordingDetails
  • statistics
  • status
  • suggestions
  • topicDetails

Alle diese Teile sind Objekte, die verschachtelte Eigenschaften enthalten. Sie können sich diese Objekte als Gruppen von Metadatenfeldern vorstellen, die der API-Server möglicherweise abruft. Daher müssen Sie mit dem Parameter part die Ressourcenkomponenten auswählen, die Ihre Anwendung tatsächlich verwendet. Diese Anforderung erfüllt zwei wichtige Zwecke:

  • Dadurch wird die Latenz verringert, da der API-Server keine Zeit mit dem Abrufen von Metadatenfeldern verbringen muss, die Ihre Anwendung nicht verwendet.
  • Dadurch wird die Bandbreitennutzung reduziert, da die Menge unnötiger Daten, die Ihre Anwendung möglicherweise abruft, verringert oder ganz vermieden wird.

Im Laufe der Zeit, wenn Ressourcen weitere Teile hinzufügen, werden diese Vorteile nur noch größer, da Ihre Anwendung keine neu eingeführten Eigenschaften anfordert, die sie nicht unterstützt.

fields-Parameter verwenden

Mit dem Parameter fields wird die API-Antwort gefiltert. Sie enthält nur die Ressourcenabschnitte, die im Parameterwert part angegeben sind, sodass die Antwort nur eine bestimmte Gruppe von Feldern enthält. Mit dem Parameter fields können Sie verschachtelte Attribute aus einer API-Antwort entfernen und so die Bandbreitennutzung weiter reduzieren. Der Parameter part kann nicht verwendet werden, um verschachtelte Attribute aus einer Antwort herauszufiltern.

Die folgenden Regeln beschreiben die unterstützte Syntax für den fields-Parameterwert, die grob auf der XPath-Syntax basiert:

  • Mit einer durch Kommas getrennten Liste (fields=a,b) kannst du mehrere Felder auswählen.
  • Verwenden Sie ein Sternchen (fields=*) als Platzhalter, um alle Felder zu identifizieren.
  • Verwenden Sie Klammern (fields=a(b,c)), um eine Gruppe verschachtelter Attribute anzugeben, die in die API-Antwort aufgenommen werden sollen.
  • Verwenden Sie einen Schrägstrich (fields=a/b), um eine verschachtelte Property anzugeben.

In der Praxis sind oft mehrere verschiedene fields-Parameterwerte zulässig, um dieselbe API-Antwort abzurufen. Wenn Sie beispielsweise die Playlist-Element-ID, den Titel und die Position für jedes Element in einer Playlist abrufen möchten, können Sie einen der folgenden Werte verwenden:

  • fields=items/id,playlistItems/snippet/title,playlistItems/snippet/position
  • fields=items(id,snippet/title,snippet/position)
  • fields=items(id,snippet(title,position))

Hinweis: Wie bei allen Abfrageparameterwerten muss der Wert des Parameters fields URL-codiert sein. Die Beispiele in diesem Dokument enthalten für eine bessere Lesbarkeit keine Codierung.

Beispiel für Teilanfragen

Die folgenden Beispiele zeigen, wie Sie die Parameter part und fields verwenden können, um sicherzustellen, dass API-Antworten nur die Daten enthalten, die von Ihrer Anwendung verwendet werden:

  1. Beispiel 1 gibt eine Videoressource mit vier Teilen sowie kind- und etag-Properties zurück.
  2. Beispiel 2 gibt eine Videoressource mit zwei Teilen sowie den Attributen kind und etag zurück.
  3. Beispiel 3 gibt eine Videoressource zurück, die zwei Teile enthält, aber die Attribute kind und etag ausschließt.
  4. Beispiel 4 gibt eine Videoressource zurück, die zwei Teile enthält, aber kind und etag sowie einige verschachtelte Properties im snippet-Objekt der Ressource ausschließt.
Beispiel 1
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,contentDetails,statistics,status

Description: This example retrieves a video resource and identifies several
             resource parts that should be included in the API response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "contentDetails": {
    "duration": "PT15M51S",
    "aspectRatio": "RATIO_16_9"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   },
   "status": {
    "uploadStatus": "STATUS_PROCESSED",
    "privacyStatus": "PRIVACY_PUBLIC"
   }
  }
 ]
}
Beispiel 2
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics

Description: This example modifies the part parameter value so that the
             contentDetails and status properties are not included
             in the response.

API response:


{ 
 "kind": "youtube#videoListResponse",
 "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/sDAlsG9NGKfr6v5AlPZKSEZdtqA\"",
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "kind": "youtube#video",
   "etag": "\"UCBpFjp2h75_b92t44sqraUcyu0/iYynQR8AtacsFUwWmrVaw4Smb_Q\"",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Beispiel 3
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &part=snippet,statistics&fields=items(id,snippet,statistics)

Description: This example adds the fields parameter to remove all
             kind and etag properties from the API response.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "publishedAt": "2012-06-20T22:45:24.000Z",
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "description": "Antonio Fuentes speaks to us and takes questions on working with Google APIs and OAuth 2.0.",
    "thumbnails": {
     "default": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/default.jpg"
     },
     "medium": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/mqdefault.jpg"
     },
     "high": {
      "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"
     }
    },
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}
Beispiel 4
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
     &fields=items(id,snippet(channelId,title,categoryId),statistics)&part=snippet,statistics

Description: This example modifies the fields parameter from example 3
             so that in the API response, each video resource's snippet
             object only includes the channelId, title,
             and categoryId properties.

API response:


{ 
 "videos": [
  {
   "id": "7lCDEYXw3mM",
   "snippet": { 
    "channelId": "UC_x5XG1OV2P6uZZ5FSM9Ttw",
    "title": "Google I/O 101: Q&A On Using Google APIs",
    "categoryId": "28"
   },
   "statistics": {
    "viewCount": "3057",
    "likeCount": "25",
    "dislikeCount": "0",
    "favoriteCount": "17",
    "commentCount": "12"
   }
  }
 ]
}

Leistungsoptimierung

ETags verwenden

ETags, ein Standardteil des HTTP-Protokolls, ermöglichen es Anwendungen, auf eine bestimmte Version einer bestimmten API-Ressource zu verweisen. Die Ressource kann ein ganzer Feed oder ein Element in diesem Feed sein. Diese Funktion unterstützt die folgenden Anwendungsfälle:

  • Caching und bedingtes Abrufen: Ihre Anwendung kann API-Ressourcen und ihre ETags im Cache speichern. Wenn Ihre Anwendung dann eine gespeicherte Ressource noch einmal anfordert, gibt sie das ETag an, das mit dieser Ressource verknüpft ist. Wenn sich die Ressource geändert hat, gibt die API die geänderte Ressource und das ETag zurück, das mit dieser Version der Ressource verknüpft ist. Wenn sich die Ressource nicht geändert hat, gibt die API eine HTTP-304-Antwort (Not Modified) zurück, die angibt, dass sich die Ressource nicht geändert hat. Ihre Anwendung kann so die Latenz und die Bandbreitennutzung reduzieren.

    Die Clientbibliotheken für Google APIs unterscheiden sich in ihrer Unterstützung von ETags. Die JavaScript-Clientbibliothek unterstützt beispielsweise ETags über eine weiße Liste für zulässige Anfrageheader, die If-Match und If-None-Match enthält. Durch die Zulassungsliste wird das normale Browser-Caching ermöglicht. Wenn sich das ETag einer Ressource nicht geändert hat, kann die Ressource aus dem Browser-Cache bereitgestellt werden. Der Obj-C-Client unterstützt hingegen keine ETags.

  • Schutz vor unbeabsichtigtem Überschreiben von Änderungen: ETags tragen dazu bei, dass mehrere API-Clients nicht versehentlich die Änderungen des jeweils anderen überschreiben. Beim Aktualisieren oder Löschen einer Ressource kann Ihre Anwendung das ETag der Ressource angeben. Wenn das ETag nicht mit der neuesten Version der Ressource übereinstimmt, schlägt die API-Anfrage fehl.

Die Verwendung von ETags in Ihrer Anwendung bietet mehrere Vorteile:

  • Die API reagiert schneller auf Anfragen nach im Cache gespeicherten, aber unveränderten Ressourcen, was zu einer geringeren Latenz und Bandbreitennutzung führt.
  • Ihre Anwendung überschreibt nicht versehentlich Änderungen an einer Ressource, die von einem anderen API-Client vorgenommen wurden.

Die Google APIs Client Library for JavaScript unterstützt die HTTP-Anfrageheader If-Match und If-None-Match. Dadurch können ETags im Kontext des normalen Browser-Cachings verwendet werden.

gzip verwenden

Sie können die für jede API-Antwort benötigte Bandbreite auch reduzieren, indem Sie die GZIP-Komprimierung aktivieren. Auch wenn für Ihre Anwendung zusätzliche CPU-Zeit für die Dekomprimierung von API-Antworten erforderlich ist, überwiegt in der Regel der Vorteil, dass weniger Netzwerkressourcen benötigt werden.

Sie müssen zwei Schritte ausführen, um eine mit gzip codierte Antwort zu erhalten:

  • Setzen Sie den HTTP-Anfrageheader Accept-Encoding auf gzip.
  • Ändern Sie Ihren User-Agent so, dass er den String gzip enthält.

Die folgenden Beispiel-HTTP-Header veranschaulichen diese Anforderungen für die Aktivierung der GZIP-Komprimierung:

Accept-Encoding: gzip
User-Agent: my program (gzip)