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 erläutert. Außerdem finden Sie hier eine Übersicht über die verschiedenen Funktionen, die die API unterstützt.

Vorbereitung

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

2. Erstelle ein Projekt in der Google Developers Console und fordere Autorisierungsdaten an, damit deine 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 Cloud Console auf und wählen Sie das Projekt aus, das Sie gerade registriert haben.
   2. Rufen Sie die Seite „Aktivierte APIs“ auf. Prüfe, ob die YouTube Data API in der Liste der aktivierten APIs enthalten ist. Wenn dies nicht der Fall ist, öffnen Sie die API-Bibliothek und aktivieren Sie die API.

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 wichtigsten 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 eine individuelle Datenentität mit einer eindeutigen Kennung. 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. Beispielsweise wird mit der Property snippet.resourceId.videoId einer playlistItem-Ressource eine Videoressource identifiziert, die wiederum vollständige Informationen zum Video enthält. Ein weiteres Beispiel: Ein Suchergebnis enthält entweder die Property videoId, playlistId oder channelId, die 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. Beispielsweise wird mit der Methode videos.rate eine Nutzerbewertung mit einem Video verknüpft und mit der Methode thumbnails.set ein Video-Thumbnail auf YouTube hochgeladen und mit einem Video verknüpft.

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 den aktuell authentifizierten Nutzer oder private Daten abgerufen werden können.

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 unbillig beeinträchtigen oder den Zugriff für andere einschränken. Für alle API-Anfragen, auch für ungültige Anfragen, fallen mindestens Kosten in Höhe eines Kontingentpunkts an. Das für Ihre Anwendung verfügbare Kontingent finden Sie in der API Console.

Projekte, für die die YouTube Data API aktiviert ist, haben ein Standardkontingent von 100 search.list-Aufrufen,100 videos.insert-Aufrufen und 10.000 Einheiten pro Tag für alle anderen Endpunkte zusammen. 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. Ihre Kontingentnutzung können Sie in der API Console auf der Seite Kontingente einsehen.

Hinweis: Wenn du das Kontingentlimit erreichst, kannst du ein zusätzliches Kontingent beantragen. Fülle dazu das Formular zur Kontingenterweiterung für YouTube API-Dienste aus.

Kontingentnutzung berechnen

Google berechnet die Kontingentnutzung, indem jeder Anfrage Kosten zugewiesen werden. Für verschiedene Arten von Vorgängen gelten unterschiedliche Kontingentkosten. 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 1 Einheiten.
• Ein Video-Upload kostet 1 Einheit.

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 Arbeitsspeicherressourcen 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 Attribute in den angeforderten Ressourcenteilen zurückgegeben werden.

part-Parameter verwenden

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

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

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

• Dadurch wird die Latenz reduziert, da der API-Server keine Zeit damit verbringt, Metadatenfelder abzurufen, die Ihre Anwendung nicht verwendet.
• Die Bandbreitennutzung wird reduziert, da die Menge der unnötigen Daten, die Ihre Anwendung möglicherweise abruft, reduziert (oder eliminiert) wird.

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

Parameter fields verwenden

Mit dem Parameter fields wird die API-Antwort gefiltert. Sie enthält nur die im Parameterwert part angegebenen Ressourcenteile, 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 zu kennzeichnen.

In der Praxis ermöglichen diese Regeln oft, dass mehrere verschiedene fields-Parameterwerte dieselbe API-Antwort abrufen. Wenn du beispielsweise die ID, den Titel und die Position jedes Elements in einer Playlist abrufen möchtest, kannst du 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 Suchparameterwerten muss der fields Parameterwert URL-codiert sein. Die Beispiele in diesem Dokument enthalten für eine bessere Lesbarkeit keine Codierung.

Beispiele für partielle Anfragen

In den folgenden Beispielen wird gezeigt, wie Sie die Parameter part und fields verwenden können, damit 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. In Beispiel 2 wird eine Videoressource zurückgegeben, die zwei Teile sowie die Properties kind und etag enthält.
3. Beispiel 3 gibt eine Videoressource mit zwei Teilen zurück, schließt aber die Properties kind und etag aus.
4. In Beispiel 4 wird eine Videoressource zurückgegeben, die zwei Teile enthält, aber kind und etag sowie einige verschachtelte Properties 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)