YouTube Data API – Übersicht

Einführung

Dieses Dokument richtet sich an Entwickler, die Anwendungen für die Interaktion mit YouTube erstellen möchten. Darin werden die grundlegenden Konzepte von YouTube und der API selbst erläutert. Außerdem erhalten Sie einen Überblick über die verschiedenen Funktionen, 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 fordern Sie Anmeldedaten für die Autorisierung an, damit Ihre Anwendung API-Anfragen senden kann.

3. Vergewissere dich nach der Erstellung deines Projekts, dass die YouTube Data API einer der Dienste ist, für den 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. Prüfe in der Liste der APIs, ob der Status der YouTube Data API Version 3 EIN lautet.

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 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 ein individuelles Datenobjekt mit einer eindeutigen ID. In der folgenden Tabelle werden die verschiedenen Ressourcentypen beschrieben, mit denen Sie über die API interagieren können.

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

Unterstützte Vorgänge

Die folgende Tabelle zeigt die gängigsten Methoden, die von der API unterstützt werden. Einige Ressourcen unterstützen auch andere Methoden, die für diese Ressourcen spezifischere Funktionen ausführen. Die Methode videos.rate verknüpft beispielsweise eine Nutzerbewertung mit einem Video und die Methode thumbnails.set lädt ein Video-Thumbnail auf YouTube hoch und verknüpft es mit einem Video.

Die API unterstützt derzeit Methoden zum Auflisten der unterstützten Ressourcentypen und 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 zum Einfügen, Aktualisieren oder Löschen von Ressourcen 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 private Anfragen abrufen können.

Kontingentnutzung

Die YouTube Data API verwendet 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, fallen mindestens ein Punktkontingent an. Das für Ihre Anwendung verfügbare Kontingent finden Sie in der API Console.

Projekte, bei denen die YouTube Data API aktiviert wird, haben eine standardmäßige Kontingentzuteilung von 10.000 Einheiten pro Tag – ein Betrag, der für die überwiegende Mehrheit unserer API-Nutzer ausreicht. Das Standardkontingent kann sich ändern und hilft uns dabei, die Kontingentzuweisung zu optimieren und unsere Infrastruktur auf eine Weise zu skalieren, die für unsere API-Nutzer sinnvoller ist. Sie können Ihre Kontingentnutzung in der API-Konsole auf der Seite Kontingente einsehen.

Hinweis:Wenn Sie das Kontingentlimit erreichen, können Sie bis zum Abschluss der Kontingenterweiterung Antragsformular für die YouTube API-Dienste an.

Kontingentnutzung berechnen

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

• Eine Leseoperation, die eine Liste von Ressourcen – Kanälen, Videos, Playlists – abruft, in der Regel kostet 1 Einheit.
• Ein Schreibvorgang, der eine Ressource erstellt, aktualisiert oder löscht, verursacht in der Regel Kosten 50 Einheiten.
• Eine Suchanfrage kostet 100 Einheiten.
• Ein Video-Upload kostet 1600 Einheiten.

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

Teilressourcen

Die API ermöglicht und erfordert das Abrufen von Teilressourcen, sodass die Anwendungen das Übertragen, Parsen und Speichern nicht benötigter Daten vermeiden. Dieser Ansatz sorgt auch dafür, dass die API Netzwerk-, CPU- und Arbeitsspeicherressourcen effizienter verwendet.

Die API unterstützt zwei Anfrageparameter, die in den folgenden Abschnitten erläutert werden und mit denen Sie die Ressourceneigenschaften identifizieren können, die in API-Antworten enthalten sein sollen.

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

Verwendung des part-Parameters

Der Parameter part ist ein erforderlicher Parameter für jede API-Anfrage, die eine Ressource abruft oder zurückgibt. Der Parameter gibt mindestens ein (nicht verschachteltes) übergeordnetes Ressourcenattribut an, das in einer API-Antwort enthalten sein sollte. Eine Ressource vom Typ video 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 der API-Server abrufen könnte (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 verringert die Latenz, da der API-Server keine Zeit für das Abrufen von Metadatenfeldern benötigt, die nicht von Ihrer Anwendung verwendet werden.
• Sie reduziert die Bandbreitennutzung, indem die Menge unnötiger Daten, die Ihre Anwendung möglicherweise abrufen könnte, reduziert (oder beseitigt) wird.

Wenn im Laufe der Zeit Ressourcen hinzugefügt werden, werden diese Vorteile nur zunehmen, da Ihre Anwendung keine neu eingeführten Properties anfordert, die nicht unterstützt werden.

Verwendung des fields-Parameters

Der Parameter fields filtert die API-Antwort, die nur die im Parameterwert part identifizierten 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 so die Bandbreitennutzung weiter reduzieren. Der Parameter part kann nicht verwendet werden, um verschachtelte Eigenschaften aus einer Antwort zu filtern.

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

• Verwende eine durch Kommas getrennte Liste (fields=a,b), um mehrere Felder auszuwählen.
• Verwenden Sie ein Sternchen (fields=*) als Platzhalter, um alle Felder anzugeben.
• Verwenden Sie Klammern (fields=a(b,c)), um eine Gruppe verschachtelter Attribute anzugeben, die in der API-Antwort enthalten sein sollen.
• Verwenden Sie einen Schrägstrich (fields=a/b), um eine verschachtelte Property anzugeben.

In der Praxis erlauben diese Regeln häufig, dass mehrere verschiedene fields-Parameterwerte dieselbe API-Antwort abrufen. Wenn Sie beispielsweise die ID, den Titel und die Position aller Elemente 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 veranschaulichen, wie Sie mit den Parametern part und fields dafür sorgen können, dass API-Antworten nur die Daten enthalten, die von Ihrer Anwendung verwendet werden:

1. Beispiel 1 gibt eine Videoressource zurück, die vier Teile sowie die Eigenschaften kind und etag enthält.
2. In Beispiel 2 wird eine Videoressource zurückgegeben, die zwei Teile sowie die Properties kind und etag enthält.
3. In Beispiel 3 wird eine Videoressource zurückgegeben, die zwei Teile enthält, aber die Properties 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 Eigenschaften im snippet-Objekt der Ressource ausschließt.

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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"
   }
  }
 ]
}

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

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