Présentation de l'API YouTube Data

Introduction

Ce document s'adresse aux développeurs qui souhaitent écrire des applications interagissant avec YouTube. Il explique les concepts de base de YouTube et de l'API elle-même. Il fournit également une présentation des 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 console Google Developers et obtenez des identifiants d'autorisation pour que votre application puisse envoyer des requêtes API.

  3. Après avoir créé votre projet, assurez-vous que l'API YouTube Data fait partie des services auxquels votre application est enregistrée pour l'utilisation :

    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 de l'API YouTube Data v3 est ACTIVÉ.

  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 de base du format de données JSON (JavaScript Object Notation). JSON est un format de données courant qui ne dépend pas d'un 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 disposant 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 sur une action effectuée par un utilisateur spécifique sur le site YouTube. Les actions des utilisateurs qui sont signalées dans les flux d'activité incluent, entre autres, l'évaluation d'une vidéo, le partage d'une vidéo, l'ajout d'une vidéo à ses favoris et la publication d'un bulletin sur une chaîne.
channel Contient des informations sur une seule chaîne YouTube.
channelBanner Identifie l'URL à utiliser pour définir une image récemment importée comme bannière d'une 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 d'une chaîne, ses vidéos les plus populaires ou les vidéos d'une ou plusieurs playlists.
guideCategory Identifie une catégorie que YouTube associe aux chaînes en fonction de leur contenu ou d'autres indicateurs, comme la popularité. Les catégories du guide visent à organiser les chaînes de manière à ce que les utilisateurs YouTube puissent trouver plus facilement les contenus qu'ils recherchent. Bien que les chaînes puissent être associées à une ou plusieurs catégories du guide, il n'est pas garanti qu'elles y figurent.
i18nLanguage Identifie une langue d'application compatible avec le site Web YouTube. La langue de l'application peut également être appelée langue de l'interface utilisateur.
i18nRegion Identifie une zone géographique qu'un utilisateur YouTube peut sélectionner comme région de contenu préférée. La région de contenu peut également être appelée "paramètres régionaux du contenu".
playlist Représente une playlist YouTube unique. Une playlist est un ensemble de vidéos qui peuvent être regardées de manière séquentielle 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 qui correspondent 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, comme une vidéo, il ne possède pas ses propres données persistantes.
subscription Contient des informations sur l'abonnement d'un utilisateur YouTube. Un abonnement permet à un utilisateur de recevoir des notifications lorsque de nouvelles vidéos sont ajoutées à une chaîne ou lorsqu'un autre utilisateur effectue l'une des actions suivantes sur YouTube : mettre en ligne une vidéo, évaluer une vidéo ou commenter une vidéo.
thumbnail Identifie les miniatures 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 aux vidéos importées.
watermark Identifie une image qui s'affiche lors de la lecture des vidéos d'une chaîne spécifiée. Le propriétaire de la chaîne peut également spécifier une chaîne cible vers laquelle l'image est associée, ainsi que des informations temporelles qui déterminent quand le filigrane apparaît pendant la lecture des vidéos et pendant combien de temps il est visible.

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. Par exemple, un résultat de recherche contient une propriété videoId, playlistId ou channelId qui identifie une ressource vidéo, playlist ou chaîne spécifique.

Opérations prises en charge

Le tableau suivant présente les méthodes les plus courantes compatibles avec l'API. Certaines ressources sont également compatibles avec d'autres méthodes qui exécutent 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 image miniature de vidéo sur YouTube et l'associe à une vidéo.

Opérations
list Récupère (GET) une liste d'une ou plusieurs ressources.
insert Crée (POST) une ressource.
update Modifie (PUT) une ressource existante pour refléter les données de votre demande.
delete Supprime (DELETE) une ressource spécifique.

L'API est actuellement compatible avec les méthodes permettant de lister chacun des types de ressources acceptés. Elle est également compatible avec les opérations d'écriture pour de nombreuses ressources.

Le tableau ci-dessous indique les opérations compatibles avec 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 acceptent les requêtes autorisées et non autorisées. Les requêtes non autorisées ne récupèrent que les données publiques, tandis que les requêtes autorisées peuvent également récupérer des informations sur l'utilisateur actuellement authentifié ou privées.

Opérations compatibles
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

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

Les projets qui activent l'API YouTube Data disposent d'une allocation de quota par défaut de 10 000 unités par jour, ce qui est suffisant pour la grande majorité de nos utilisateurs d'API. Le quota par défaut, qui est susceptible d'être modifié, nous aide à optimiser les allocations de quota et à faire évoluer notre infrastructure de manière plus pertinente pour nos utilisateurs d'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 un quota supplémentaire en remplissant le formulaire de demande d'augmentation 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 quota varient 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.
  • La mise en ligne d'une vidéo coûte 100 unités.

Le tableau Coûts de quota pour les requêtes API indique le coût de quota de chaque méthode d'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 exige même, la récupération de ressources partielles afin que les applications évitent de transférer, d'analyser et de stocker des données inutiles. Cette approche permet également de s'assurer que l'API utilise plus efficacement les ressources réseau, CPU et de 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 ressources à inclure dans les réponses de l'API.

  • Le paramètre part identifie les groupes de propriétés qui doivent être renvoyés 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 ressource 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 ressources de premier niveau (non imbriquées) qui doivent être incluses dans une réponse d'API. Par exemple, une ressource video comporte les parties suivantes :

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

Toutes ces parties sont des objets contenant des propriétés imbriquées. Vous pouvez considérer ces objets 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 vous oblige à sélectionner les composants de ressources que votre application utilise réellement. Cette exigence a deux objectifs principaux :

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

Au fil du temps, à mesure que les ressources ajouteront des parties, ces avantages ne feront 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 ressource identifiées dans la valeur du paramètre part, de sorte que 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 ainsi davantage votre utilisation de la bande passante. (Le paramètre part ne peut pas être utilisé pour filtrer les propriétés imbriquées d'une réponse.)

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

  • Incluez une liste dont les éléments sont séparés par une virgule (fields=a,b) pour sélectionner plusieurs champs.
  • Utilisez un astérisque (fields=*) comme 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 qui seront incluses 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 autorisent souvent plusieurs valeurs de paramètre fields différentes pour 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 inclut quatre parties, ainsi que les propriétés kind et etag.
  2. L'exemple 2 renvoie une ressource vidéo qui inclut deux parties, ainsi que les propriétés kind et etag.
  3. L'exemple 3 renvoie une ressource vidéo qui inclut deux parties, mais exclut les propriétés kind et etag.
  4. L'exemple 4 renvoie une ressource vidéo qui inclut 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, qui fait partie intégrante 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 être un flux entier 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 d'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 de la ressource. Si la ressource n'a pas changé, l'API renvoie une réponse HTTP 304 (Not Modified), qui indique que la ressource n'a pas été modifiée. 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.

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

  • Protection contre l'écrasement involontaire des modifications : les ETag permettent de s'assurer que plusieurs clients API n'écrasent pas involontairement les modifications des autres. Lorsque vous mettez à jour ou supprimez une ressource, votre application peut spécifier l'ETag de la ressource. Si l'ETag ne correspond pas à la version la plus récente de cette ressource, la requête API échoue.

L'utilisation d'ETags dans votre application présente plusieurs avantages :

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

Google APIs Client Library for JavaScript est compatible avec 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 votre application ait besoin de temps CPU supplémentaire pour décompresser les réponses de l'API, 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 ces exigences pour activer la compression gzip :

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