Diese Seite wurde von der Cloud Translation API übersetzt.

YouTube Data API – Übersicht

Einführung

Dieses Dokument richtet sich an Entwickler, die Anwendungen entwickeln möchten, die mit YouTube interagieren. Darin werden die grundlegenden Konzepte von YouTube und der API selbst erläutert. Außerdem erhalten Sie einen Überblick über die verschiedenen Funktionen, die die API unterstützt.

Vorbereitung

Sie benötigen ein Google-Konto, um auf die Google API Console zuzugreifen, einen API-Schlüssel anzufordern und Ihre Anwendung zu registrieren.
Erstellen Sie ein Projekt in der Google Developers Console und rufen Sie Autorisierungsdaten ab, damit Ihre Anwendung API-Anfragen senden kann.
Stelle nach der Erstellung deines Projekts sicher, dass die YouTube Data API einer der Dienste ist, für die deine Anwendung registriert ist:
1. Gehen Sie zur API Console und wählen Sie das Projekt aus, das Sie gerade registriert haben.
2. Rufen Sie die Seite Aktivierte APIs auf. Achte darauf, dass in der Liste der APIs für die YouTube Data API Version 3 der Status AN ist.
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.
Wähle eine Client-Bibliothek aus, um deine API-Implementierung zu vereinfachen.
Machen Sie sich mit den Kernkonzepten 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 eine einzelne Datenentität mit einer eindeutigen Kennung. In der folgenden Tabelle 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 die Bewertung eines Videos, das Teilen eines Videos, das Markieren eines Videos als Favorit und das Posten eines Kanalbulletins.
`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 auf einem Kanal vorgestellt werden. Ein Bereich kann beispielsweise die neuesten Uploads eines Kanals, die beliebtesten Uploads oder Videos aus einer oder mehreren Playlists enthalten.
`guideCategory`	Gibt eine Kategorie an, die YouTube Kanälen auf der Grundlage ihrer Inhalte oder anderer Indikatoren wie der Beliebtheit zuordnet. Mithilfe von Guide-Kategorien sollen Kanäle so organisiert werden, dass YouTube-Nutzer die gesuchten Inhalte leichter finden. Kanäle können zwar einer oder mehreren Kategoriekategorien zugeordnet werden, es ist aber nicht garantiert, dass sie keiner Kategorie zugeordnet werden.
`i18nLanguage`	Kennzeichnet die Anwendungssprache, die von der YouTube-Website unterstützt wird. Die Anwendungssprache kann auch als UI-Sprache bezeichnet werden.
`i18nRegion`	Gibt ein geografisches Gebiet an, das ein YouTube-Nutzer als bevorzugte Region für Inhalte auswählen kann. Der Inhaltsbereich kann auch als Inhaltsgebietsschema bezeichnet werden.
`playlist`	Steht für eine einzelne YouTube-Playlist. Eine Playlist ist eine Sammlung von Videos, die nacheinander angesehen und mit anderen Nutzern geteilt werden können.
`playlistItem`	Kennzeichnet eine Ressource, z. B. ein Video, das Teil einer Playlist ist. Die Ressource „playlistItem“ enthält auch Details, die erklären, wie die enthaltene Ressource in der Playlist verwendet wird.
`search result`	Enthält Informationen zu einem YouTube-Video, einem YouTube-Kanal oder einer YouTube-Playlist, die mit den in einer API-Anfrage angegebenen Suchparametern übereinstimmen. Ein Suchergebnis verweist zwar auf eine eindeutig identifizierbare Ressource wie ein Video, verfügt aber nicht über eigene persistente Daten.
`subscription`	Enthält Informationen zu einem YouTube-Abo. Mit einem Abo werden Nutzer benachrichtigt, wenn einem Kanal neue Videos hinzugefügt werden oder wenn ein anderer Nutzer eine von mehreren Aktionen auf YouTube ausführt, z. B. ein Video hochlädt, ein Video bewertet oder ein Video kommentiert.
`thumbnail`	Ermittelt Miniaturansichten, die mit einer Ressource verknüpft sind.
`video`	Steht für ein einzelnes YouTube-Video.
`videoCategory`	Gibt eine Kategorie an, die mit hochgeladenen Videos verknüpft wurde oder sein könnte.
`watermark`	Kennzeichnet ein Bild, das bei der Wiedergabe der Videos eines bestimmten Kanals angezeigt wird. Der Kanalinhaber kann auch einen Zielkanal angeben, zu dem das Bildlink verknüpft ist, sowie Zeitangaben, die bestimmen, wann das Wasserzeichen während der Videowiedergabe erscheint und wie lange es sichtbar ist.

Beachten Sie, dass eine Ressource in vielen Fällen Verweise auf andere Ressourcen enthält. Das Attribut snippet.resourceId.videoId einer playlistItem-Ressource gibt beispielsweise eine Videoressource an, die wiederum vollständige Informationen über das Video enthält. Ein weiteres Beispiel: Ein Suchergebnis enthält entweder eine videoId-, playlistId- oder channelId-Eigenschaft, die eine bestimmte Video-, Playlist- oder Kanalressource angibt.

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. So wird beispielsweise bei der Methode videos.rate eine Nutzerbewertung einem Video zugeordnet und mit der Methode thumbnails.set wird ein Video-Thumbnail auf YouTube hochgeladen und mit einem Video verknüpft.

Betrieb
`list`	Ruft eine Liste mit null oder mehr Ressourcen ab (`GET`).
`insert`	Erstellt (`POST`) eine neue Ressource.
`update`	Ändert eine vorhandene Ressource (`PUT`), damit die Daten in Ihrer Anfrage widergespiegelt werden.
`delete`	Entfernt (`DELETE`) eine bestimmte Ressource.

Die API unterstützt derzeit Methoden, um alle unterstützten Ressourcentypen aufzulisten, 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. Vorgänge, bei denen Ressourcen eingefügt, aktualisiert oder gelöscht werden, erfordern immer eine Nutzerautorisierung. In einigen Fällen unterstützen list-Methoden sowohl autorisierte als auch nicht autorisierte Anfragen, bei denen nicht autorisierte Anfragen nur öffentliche Daten abrufen, während autorisierte Anfragen auch Informationen über den aktuell authentifizierten Nutzer oder nur für ihn sichtbar sind.

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

YouTube Data API nutzt ein Kontingent, um sicherzustellen, dass Entwickler den Dienst wie vorgesehen verwenden und keine Anwendungen erstellen, die die Dienstqualität auf unfaire Weise verringern oder den Zugriff für andere einschränken. Für alle API-Anfragen, einschließlich ungültiger Anfragen, wird mindestens eine 1-Punkt-Kontingentkosten berechnet. Das für Ihre Anwendung verfügbare Kontingent finden Sie in der API Console.

Für Projekte, die die YouTube Data API aktivieren, gilt standardmäßig eine Kontingentzuteilung von 10.000 Einheiten pro Tag – eine Menge, die für die überwiegende Mehrheit unserer API-Nutzer ausreicht. Das Standardkontingent kann sich ändern. Es hilft uns, die Kontingentzuweisung zu optimieren und unsere Infrastruktur auf eine für unsere API-Nutzer sinnvolle Weise zu skalieren. Ihre Kontingentnutzung können Sie auf der Seite Kontingente in der API-Konsole einsehen.

Hinweis:Wenn das Kontingentlimit erreicht ist, können Sie über das Antragsformular zur Kontingenterweiterung für YouTube API-Dienste ein zusätzliches Kontingent anfordern.

Kontingentnutzung berechnen

Google berechnet Ihre Kontingentnutzung, indem jeder Anfrage Kosten zugeteilt werden. Verschiedene Arten von Vorgängen haben unterschiedliche Kontingentkosten. Beispiel:

Ein Lesevorgang zum Abrufen einer Liste von Ressourcen – Kanälen, Videos, Playlists – kostet normalerweise 1 Einheit.
Ein Schreibvorgang, bei dem eine Ressource erstellt, aktualisiert oder gelöscht wird, kostet normalerweise 50 Einheiten.
Eine Suchanfrage kostet 100 Einheiten.
Ein Video-Upload kostet 1600 Einheiten.

In der Tabelle Kontingentkosten für API-Anfragen sehen Sie die Kontingentkosten für die einzelnen API-Methoden. Unter Berücksichtigung dieser Regeln können Sie die Anzahl der Anfragen schätzen, die Ihre Anwendung pro Tag senden könnte, ohne Ihr Kontingent zu überschreiten.

Teilweise Ressourcen

Die API ermöglicht das Abrufen von Teilressourcen, sodass Anwendungen das Übertragen, Parsen und Speichern nicht benötigter Daten vermeiden. Dies ist auch erforderlich. 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. Sie ermöglichen es Ihnen, die Ressourcenattribute zu identifizieren, die in API-Antworten enthalten sein sollen.

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

Parameter `part` verwenden

Der part-Parameter ist ein erforderlicher Parameter für jede API-Anfrage, die eine Ressource abruft oder zurückgibt. Der Parameter gibt ein oder mehrere übergeordnete (nicht verschachtelte) Ressourcenattribute an, die in einer API-Antwort enthalten sein sollten. Eine video-Ressource besteht beispielsweise aus folgenden Teilen:

snippet
contentDetails
fileDetails
player
processingDetails
recordingDetails
statistics
status
suggestions
topicDetails

All diese Teile sind Objekte, die verschachtelte Eigenschaften enthalten. Sie können sich diese Objekte als Gruppen von Metadatenfeldern vorstellen, die vom API-Server abgerufen werden können oder nicht. Daher müssen Sie für den Parameter part die Ressourcenkomponenten auswählen, die Ihre Anwendung tatsächlich verwendet. Diese Anforderung dient hauptsächlich zwei Zwecken:

Es reduziert die Latenz, da der API-Server keine Zeit damit verbringen muss, Metadatenfelder abzurufen, die Ihre Anwendung nicht verwendet.
Es reduziert die Bandbreitennutzung, indem die Menge nicht erforderlicher Daten reduziert (oder eliminiert) wird, die Ihre Anwendung abrufen könnte.

Je mehr Ressourcen hinzukommen, desto mehr werden sich diese Vorteile mit der Zeit zunehmen, da Ihre Anwendung keine neu eingeführten Eigenschaften anfordert, die sie nicht unterstützt.

Parameter `fields` verwenden

Der Parameter fields filtert die API-Antwort, die nur die im Parameterwert part angegebenen Ressourcenteile enthält, 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 dadurch die Bandbreitennutzung reduzieren. Der Parameter part kann nicht zum Filtern verschachtelter Properties aus einer Antwort verwendet werden.

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

Verwenden Sie eine durch Kommas getrennte Liste (fields=a,b), um mehrere Felder auszuwählen.
Verwenden Sie ein Sternchen (fields=*) als Platzhalter, um alle Felder zu identifizieren.
Verwenden Sie Klammern (fields=a(b,c)), um eine Gruppe verschachtelter Eigenschaften anzugeben, die in der API-Antwort enthalten sein sollen.
Gib ein verschachteltes Attribut mit einem Schrägstrich (fields=a/b) an.

In der Praxis ermöglichen diese Regeln häufig, dass verschiedene fields-Parameterwerte dieselbe API-Antwort abrufen. Wenn Sie beispielsweise die Element-ID, den Titel und die Position der Playlist 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.

Beispiele für Teilanfragen

Die folgenden Beispiele zeigen, wie Sie mit den Parametern part und fields dafür sorgen können, dass API-Antworten nur die von Ihrer Anwendung verwendeten Daten enthalten:

Beispiel 1 gibt eine Videoressource zurück, die vier Teile sowie die Eigenschaften kind und etag enthält.
Beispiel 2 gibt eine Videoressource zurück, die zwei Teile sowie die Properties kind und etag enthält.
Beispiel 3 gibt eine Videoressource zurück, die zwei Teile enthält, aber die Properties kind und etag ausschließt.
Beispiel 4 gibt eine Videoressource zurück, die zwei Teile enthält, aber kind und etag sowie einige verschachtelte Eigenschaften im Objekt snippet 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öglicht es Anwendungen, auf eine bestimmte Version einer bestimmten API-Ressource zu verweisen. Die Ressource kann ein vollständiger Feed oder ein Artikel in diesem Feed sein. Diese Funktion unterstützt die folgenden Anwendungsfälle:

Caching und bedingter Abruf: Ihre Anwendung kann API-Ressourcen und ihre ETags im Cache speichern. Wenn Ihre Anwendung dann eine gespeicherte Ressource erneut anfordert, gibt sie das mit dieser Ressource verknüpfte ETag an. Wenn die Ressource geändert wurde, gibt die API die geänderte Ressource und das mit dieser Version der Ressource verknüpfte ETag zurück. Wenn die Ressource nicht geändert wurde, gibt die API eine HTTP 304-Antwort (Not Modified) zurück, die angibt, dass die Ressource nicht geändert wurde. Ihre Anwendung kann Latenz und Bandbreitennutzung reduzieren, indem im Cache gespeicherte Ressourcen auf diese Weise bereitgestellt werden.

Die Clientbibliotheken für Google APIs unterstützen ETags unterschiedlich. Die JavaScript-Clientbibliothek unterstützt beispielsweise ETags über eine Zulassungsliste für zulässige Anfrageheader, die If-Match und If-None-Match enthalten. Die Zulassungsliste ermöglicht ein normales Browser-Caching. Wenn sich das ETag einer Ressource nicht geändert hat, kann die Ressource aus dem Browser-Cache geladen werden. Der Obj-C-Client dagegen unterstützt keine ETags.
Schutz vor dem unbeabsichtigten Überschreiben von Änderungen – ETags sorgen dafür, dass nicht unbeabsichtigt Änderungen durch mehrere API-Clients überschrieben werden. Beim Aktualisieren oder Löschen einer Ressource kann Ihre Anwendung das ETag der Ressource angeben. Wenn das ETag nicht mit der neuesten Version dieser 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 geringeren Bandbreitennutzung führt.
Ihre Anwendung überschreibt nicht versehentlich Änderungen an einer Ressource, die von einem anderen API-Client vorgenommen wurden.

Google APIs Client Library for JavaScript unterstützt die HTTP-Anfrageheader If-Match und If-None-Match. Dadurch funktionieren ETags im Kontext des normalen Browser-Caching.

gzip verwenden

Sie können auch die für jede API-Antwort benötigte Bandbreite reduzieren, indem Sie die gzip-Komprimierung aktivieren. Während Ihre Anwendung zum Dekomprimieren von API-Antworten zusätzliche CPU-Zeit benötigt, überwiegt der Vorteil, weniger Netzwerkressourcen zu verbrauchen, diese Kosten in der Regel.

Führen Sie zwei Schritte aus, um eine mit gzip codierte Antwort zu erhalten:

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

Die folgenden HTTP-Beispielheader zeigen die folgenden Anforderungen für die Aktivierung der gzip-Komprimierung:

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