Présentation de l'API YouTube Data

Introduction

Ce document est destiné aux développeurs qui souhaitent développer des applications qui interagissent avec YouTube. Il explique les concepts de base de YouTube et de l'API elle-même. Il présente également les différentes fonctions compatibles avec l'API.

Avant de commencer

  1. Vous devez disposer d'un compte Google pour accéder à la console Google APIs, demander une clé API et enregistrer votre application.

  2. Créez un projet dans la Google Developers Console et obtenez des identifiants d'autorisation pour que votre application puisse envoyer des requêtes API.

  3. Une fois votre projet créé, assurez-vous que l'API YouTube Data fait partie des services que votre application est autorisée à utiliser:

    1. Accédez à la console API, puis sélectionnez le projet que vous venez d'enregistrer.
    2. Accédez à la page API activées. Dans la liste des API, assurez-vous que l'état est activé pour YouTube Data API v3.

  4. Si votre application utilise des méthodes d'API nécessitant une autorisation d'utilisateur, consultez le guide d'authentification pour découvrir comment mettre en œuvre l'autorisation OAuth 2.0.

  5. Sélectionnez une bibliothèque cliente pour faciliter la mise en œuvre de votre API.

  6. Familiarisez-vous avec les concepts fondamentaux du format de données JSON (JavaScript Object Notation). JSON est un format de données commun qui ne dépend pas du langage et qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, accédez à json.org.

Ressources et types de ressources

Une ressource est une entité de données individuelle dotée d'un identifiant unique. Le tableau ci-dessous décrit les différents types de ressources avec lesquels vous pouvez interagir à l'aide de l'API.

Ressources
activity Contient des informations à propos d'une action effectuée par un utilisateur donné sur le site YouTube. Dans les flux d'activités, les utilisateurs peuvent, entre autres, donner leur avis sur une vidéo, la partager, ajouter une vidéo aux favoris ou publier un bulletin de chaîne.
channel Contient des informations sur une seule chaîne YouTube.
channelBanner URL à utiliser pour définir une image que vous venez de mettre en ligne comme bannière de la chaîne.
channelSection Contient des informations sur un ensemble de vidéos qu'une chaîne a choisi de mettre en avant. Par exemple, une section peut présenter les dernières vidéos mises en ligne sur une chaîne, les vidéos les plus populaires ou les vidéos d'une ou de plusieurs playlists.
guideCategory Ce paramètre identifie une catégorie que YouTube associe aux chaînes en fonction de leur contenu ou d'autres indicateurs tels que leur popularité. Les catégories de guide permettent d'organiser les chaînes de manière à permettre aux utilisateurs de YouTube de trouver plus facilement le contenu qu'ils recherchent. Même si les chaînes peuvent être associées à une ou plusieurs catégories de guide, il n'est pas garanti qu'elles n'appartiennent à aucune catégorie.
i18nLanguage Indique une langue d'application acceptée sur le site Web YouTube. Le langage de l'application peut également être appelé langage d'interface utilisateur.
i18nRegion Indique la zone géographique qu'un utilisateur YouTube peut sélectionner comme région préférée pour le contenu. La région du contenu peut également être appelée "paramètres régionaux de contenu".
playlist Représente une playlist YouTube unique. Une playlist est un ensemble de vidéos qui peuvent être regardées successivement et partagées avec d'autres utilisateurs.
playlistItem Identifie une ressource, telle qu'une vidéo, qui fait partie d'une playlist. La ressource playlistItem contient également des informations expliquant comment la ressource incluse est utilisée dans la playlist.
search result Contient des informations sur une vidéo, une chaîne ou une playlist YouTube correspondant aux paramètres de recherche spécifiés dans une requête API. Bien qu'un résultat de recherche pointe vers une ressource identifiable de manière unique, telle qu'une vidéo, il ne dispose pas de ses propres données persistantes.
subscription Contient des informations sur l'abonnement d'un utilisateur YouTube. Un abonnement avertit un utilisateur lorsque de nouvelles vidéos sont ajoutées à une chaîne ou lorsqu'un autre utilisateur effectue l'une des actions suivantes sur YouTube (par exemple, mettre en ligne une vidéo, évaluer une vidéo ou ajouter un commentaire sur une vidéo).
thumbnail Identifie les vignettes associées à une ressource.
video Représente une seule vidéo YouTube.
videoCategory Identifie une catégorie qui a été ou pourrait être associée à des vidéos mises en ligne.
watermark Identifie une image qui s'affiche lorsque les vidéos d'une chaîne donnée sont lues. Le propriétaire de la chaîne peut également spécifier une chaîne cible vers laquelle l'image renvoie, ainsi que des informations temporelles qui déterminent le moment où le filigrane apparaît lors de la lecture de la vidéo, ainsi que sa durée de visibilité.

Notez que, dans de nombreux cas, une ressource contient des références à d'autres ressources. Par exemple, la propriété snippet.resourceId.videoId d'une ressource playlistItem identifie une ressource vidéo qui, à son tour, contient des informations complètes sur la vidéo. Autre exemple : un résultat de recherche contient une propriété videoId, playlistId ou channelId qui identifie une vidéo, une playlist ou une chaîne spécifique.

Opérations compatibles

Le tableau suivant présente les méthodes les plus courantes compatibles avec l'API. Certaines ressources acceptent également d'autres méthodes qui effectuent des fonctions plus spécifiques à ces ressources. Par exemple, la méthode videos.rate associe une note d'utilisateur à une vidéo, et la méthode thumbnails.set importe une miniature de vidéo sur YouTube et l'associe à une vidéo.

Opérations
list Récupère (GET) une liste comportant zéro ou plusieurs ressources.
insert Crée (POST) une nouvelle ressource.
update Modifie (PUT) une ressource existante pour refléter les données dans votre requête.
delete Supprime (DELETE) une ressource spécifique.

L'API accepte actuellement des méthodes permettant de répertorier chacun des types de ressources compatibles, ainsi que les opérations d'écriture pour de nombreuses ressources.

Le tableau ci-dessous identifie les opérations compatibles avec les différents types de ressources. Les opérations d'insertion, de mise à jour ou de suppression de ressources nécessitent toujours une autorisation de l'utilisateur. Dans certains cas, les méthodes list sont compatibles avec les requêtes autorisées et non autorisées, où les requêtes non autorisées récupèrent uniquement les données publiques, tandis que les requêtes autorisées peuvent également récupérer des informations sur l'utilisateur actuellement authentifié ou la confidentialité de celles-ci.

Opérations disponibles
list insert update delete
activity
caption
channel
channelBanner
channelSection
comment
commentThread
guideCategory
i18nLanguage
i18nRegion
playlist
playlistItem
search result
subscription
thumbnail
video
videoCategory
watermark

Utilisation du quota

Le YouTube Data API utilise un quota pour s'assurer que les développeurs utilisent le service comme prévu et ne pas créer d'applications qui réduisent injustement la qualité du service ou limitent l'accès de tiers. Toutes les requêtes API, y compris les requêtes non valides, entraînent au moins un coût de quota d'un point. Vous trouverez le quota disponible pour votre application dans API Console.

Pour les projets qui activent l'API YouTube Data,le quota par défaut est de 10 000 unités par jour, ce qui est suffisant pour l'immense majorité des utilisateurs de notre API. Le quota par défaut, qui est susceptible de changer, nous aide à optimiser les allocations de quota et à faire évoluer notre infrastructure de façon plus pertinente pour les utilisateurs de nos API. Vous pouvez consulter votre utilisation des quotas sur la page Quotas de la console API.

Remarque:Si vous atteignez la limite de quota, vous pouvez demander une augmentation de quota en remplissant le formulaire de demande d'extension de quota pour les services d'API YouTube.

Calculer l'utilisation des quotas

Google calcule votre utilisation du quota en attribuant un coût à chaque requête. Les coûts de quotas diffèrent selon les types d'opérations. Exemple :

  • Une opération de lecture qui récupère une liste de ressources (chaînes, vidéos, playlists) coûte généralement une unité.
  • Une opération d'écriture qui crée, met à jour ou supprime une ressource coûte généralement 50 unités.
  • Une requête de recherche coûte 100 unités.
  • Le coût de l'importation d'une vidéo est de 1600 unités.

Le tableau Coûts des quotas pour les requêtes API indique le coût des quotas pour chaque méthode API. En gardant ces règles à l'esprit, vous pouvez estimer le nombre de requêtes que votre application peut envoyer par jour sans dépasser votre quota.

Ressources partielles

L'API autorise, et nécessite réellement, la récupération de ressources partielles afin que les applications évitent aux applications de transférer, d'analyser et de stocker des données inutiles. Cette approche garantit également que l'API utilise plus efficacement les ressources réseau, CPU et mémoire.

L'API accepte deux paramètres de requête, expliqués dans les sections suivantes, qui vous permettent d'identifier les propriétés de ressource à inclure dans les réponses de l'API.

  • Le paramètre part identifie les groupes de propriétés à renvoyer pour une ressource.
  • Le paramètre fields filtre la réponse de l'API pour ne renvoyer que des propriétés spécifiques dans les parties de ressources demandées.

Utiliser le paramètre part

Le paramètre part est obligatoire pour toute requête API qui récupère ou renvoie une ressource. Le paramètre identifie une ou plusieurs propriétés de ressource de premier niveau (non imbriquées) à inclure dans une réponse de l'API. Par exemple, une ressource video se compose des éléments suivants:

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

Toutes ces parties sont des objets contenant des propriétés imbriquées, et vous pouvez les considérer comme des groupes de champs de métadonnées que le serveur d'API peut (ou non) récupérer. Par conséquent, le paramètre part nécessite que vous sélectionniez les composants de ressources utilisés par votre application. Cette exigence répond à deux objectifs clés:

  • Elle réduit la latence en empêchant le serveur d'API de récupérer les champs de métadonnées que votre application n'utilise pas.
  • Elle réduit l'utilisation de la bande passante en réduisant (ou en éliminant) la quantité de données inutiles que votre application peut récupérer.

Au fil du temps, à mesure que les ressources ajoutent des éléments, ces avantages ne font qu'augmenter, car votre application ne demandera pas de nouvelles propriétés qu'elle ne prend pas en charge.

Utiliser le paramètre fields

Le paramètre fields filtre la réponse de l'API, qui ne contient que les parties de la ressource identifiées dans la valeur du paramètre part. Ainsi, la réponse n'inclut qu'un ensemble spécifique de champs. Le paramètre fields vous permet de supprimer les propriétés imbriquées d'une réponse d'API et de réduire davantage l'utilisation de la bande passante. (Le paramètre part ne peut pas être utilisé pour filtrer des propriétés imbriquées à partir d'une réponse.)

Les règles suivantes expliquent la syntaxe acceptée pour la valeur du paramètre fields, qui repose globalement sur la syntaxe XPath:

  • Utilisez une liste d'éléments séparés par une virgule (fields=a,b) pour sélectionner plusieurs champs.
  • Utilisez un astérisque (fields=*) en tant que caractère générique pour identifier tous les champs.
  • Utilisez des parenthèses (fields=a(b,c)) pour spécifier un groupe de propriétés imbriquées à inclure dans la réponse de l'API.
  • Utilisez une barre oblique (fields=a/b) pour identifier une propriété imbriquée.

En pratique, ces règles permettent souvent à plusieurs valeurs de paramètre fields différentes de récupérer la même réponse d'API. Par exemple, si vous souhaitez récupérer l'ID, le titre et la position de chaque élément d'une playlist, vous pouvez utiliser l'une des valeurs suivantes:

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

Remarque : Comme toutes les valeurs de paramètre de requête, la valeur du paramètre fields doit être encodée au format URL. Pour faciliter la lecture, les exemples de ce document omettent l'encodage.

Exemples de requêtes partielles

Les exemples ci-dessous montrent comment utiliser les paramètres part et fields pour vous assurer que les réponses de l'API n'incluent que les données utilisées par votre application:

  1. L'exemple 1 renvoie une ressource vidéo qui comprend quatre parties, ainsi que les propriétés kind et etag.
  2. L'exemple 2 renvoie une ressource vidéo qui comprend deux parties, ainsi que les propriétés kind et etag.
  3. L'exemple 3 renvoie une ressource vidéo qui comprend deux parties, mais exclut les propriétés kind et etag.
  4. L'exemple 4 renvoie une ressource vidéo qui comprend deux parties, mais exclut kind et etag, ainsi que certaines propriétés imbriquées dans l'objet snippet de la ressource.
Exemple 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" } } ] }
Exemple 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" } } ] }
Exemple 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" } } ] }
Exemple 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" } } ] }

Optimiser les performances

Utiliser les ETags

ETags, une partie standard du protocole HTTP, permet aux applications de faire référence à une version spécifique d'une ressource d'API particulière. La ressource peut correspondre à un flux complet ou à un élément de ce flux. Cette fonctionnalité est compatible avec les cas d'utilisation suivants:

  • Mise en cache et récupération conditionnelle : votre application peut mettre en cache les ressources API et leurs ETag. Ensuite, lorsque votre application demande à nouveau une ressource stockée, elle spécifie l'ETag associé à cette ressource. Si la ressource a été modifiée, l'API renvoie la ressource modifiée et l'ETag associé à cette version. Si la ressource n'a pas changé, l'API renvoie une réponse HTTP 304 (Not Modified), ce qui indique que la ressource n'a pas changé. Votre application peut réduire la latence et l'utilisation de la bande passante en diffusant les ressources mises en cache de cette manière.

    Les bibliothèques clientes des API Google ne sont pas compatibles avec les ETag. Par exemple, la bibliothèque cliente JavaScript accepte les ETag via une liste blanche pour les en-têtes de requêtes autorisés, qui inclut If-Match et If-None-Match. La liste blanche permet une mise en cache normale du navigateur. Ainsi, si l'ETag d'une ressource n'a pas changé, celle-ci peut être diffusée à partir du cache du navigateur. En revanche, le client Obj-C n'est pas compatible avec les ETag.

  • Protection contre les remplacements involontaires de modifications : les ETag permettent d'éviter que plusieurs clients API n'écrasent involontairement leurs modifications respectives. Lors de la mise à jour ou de la suppression d'une ressource, votre application peut spécifier son ETag. Si l'ETag ne correspond pas à la version la plus récente de cette ressource, la requête API échoue.

L'utilisation des ETag dans votre application offre plusieurs avantages:

  • L'API répond plus rapidement aux requêtes de ressources mises en cache, mais inchangées, ce qui se traduit par une latence plus faible et une utilisation réduite de la bande passante.
  • Votre application n'écrasera pas involontairement les modifications apportées à une ressource à partir d'un autre client API.

Google APIs Client Library for JavaScript accepte les en-têtes de requête HTTP If-Match et If-None-Match, ce qui permet aux ETag de fonctionner dans le contexte de la mise en cache normale du navigateur.

Utiliser gzip

Vous pouvez également réduire la bande passante requise pour chaque réponse de l'API en activant la compression gzip. Bien que la décompression des réponses d'API nécessite du temps CPU supplémentaire pour votre application, l'avantage de consommer moins de ressources réseau l'emporte généralement sur ce coût.

Pour recevoir une réponse encodée au format gzip, vous devez effectuer deux opérations:

  • Définissez l'en-tête de requête HTTP Accept-Encoding sur gzip.
  • Modifiez votre user-agent pour qu'il contienne la chaîne gzip.

Les exemples d'en-têtes HTTP ci-dessous illustrent les exigences suivantes pour l'activation de la compression gzip:

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