Présentation de l'API YouTube Data

Introduction

Ce document est destiné aux développeurs qui souhaitent créer des applications qui interagissent avec YouTube. Il explique les concepts de base de YouTube et de l'API elle-même. Il fournit également un aperçu 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 Google Developers Console et obtenez les identifiants d'autorisation afin que votre application puisse envoyer des requêtes API.

  3. Une fois votre projet créé, assurez-vous que l'API YouTube Data est l'un des services enregistrés pour votre application:

    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, vérifiez que l'état de la version 3 de l'API YouTube Data 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, indépendant du langage, 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 sur une action effectuée par un utilisateur donné sur le site YouTube. Les actions des utilisateurs signalées dans les flux d'activités incluent, entre autres, la classification et le partage d'une vidéo, son ajout aux favoris ou la publication d'un bulletin de sa chaîne.
channel Contient des informations sur une seule chaîne YouTube.
channelBanner Identifie l'URL à utiliser pour définir une image nouvellement mise en ligne comme image de bannière pour une chaîne.
channelSection Contient des informations sur un ensemble de vidéos choisi par une chaîne. Par exemple, une section peut présenter les dernières vidéos mises en ligne, les vidéos les plus populaires ou les vidéos d'une ou plusieurs playlists.
guideCategory Identifie une catégorie que YouTube associe à des chaînes en fonction de leur contenu ou d'autres indicateurs, comme la popularité. Les catégories de guides visent à organiser les chaînes de façon à permettre aux utilisateurs YouTube de trouver plus facilement les contenus qu'ils recherchent. Bien que les chaînes puissent être associées à une ou plusieurs catégories de guides, il n'est pas garanti qu'elles appartiennent à des catégories spécifiques.
i18nLanguage Identifie une langue d'application acceptée par le site Web YouTube. La langue de l'application peut également être désignée comme 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 est également appelée "paramètres régionaux du contenu".
playlist Représente une seule playlist YouTube. 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 détails 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 façon unique, comme une vidéo, il ne possède pas ses propres données persistantes.
subscription Contient des informations sur un abonnement utilisateur YouTube. Un abonnement informe l'utilisateur lorsque de nouvelles vidéos sont ajoutées à une chaîne ou lorsqu'un autre utilisateur effectue l'une des actions sur YouTube, comme mettre en ligne une vidéo, donner son avis ou commenter une vidéo.
thumbnail Identifie les images 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 à des vidéos mises en ligne.
watermark Identifie une image qui s'affiche pendant la lecture des vidéos d'une chaîne spécifique. Le propriétaire de la chaîne peut également spécifier une chaîne cible à laquelle l'image est associée, ainsi que des informations sur le moment où le filigrane s'affiche pendant la lecture de la vidéo et pendant combien de temps elle sera 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 contient à son tour 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 ressource de chaîne particulière.

Opérations compatibles

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 des visiteurs à une vidéo, tandis que 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 de zéro ou plusieurs ressources.
insert Crée (POST) une ressource.
update Modifie (PUT) une ressource existante pour refléter les données de votre requête.
delete Supprime (DELETE) une ressource spécifique.

L'API est actuellement compatible avec les méthodes permettant de lister tous les types de ressources compatibles, ainsi qu'avec les opérations d'écriture pour de nombreuses ressources.

Le tableau ci-dessous identifie 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 utilisateur. Dans certains cas, les méthodes list sont compatibles avec 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 les rendre privées.

Opérations acceptées
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 de manière injuste la qualité du service ou limitent l'accès pour d'autres. Toutes les requêtes API, y compris les requêtes non valides, entraînent au moins un coût de quota d'un point. Le quota disponible pour votre application est indiqué dans API Console.

Les projets pour lesquels l'API YouTube Data est activée disposent d'un quota d'allocation par défaut de 10 000 unités par jour, ce qui est suffisant pour la grande majorité des utilisateurs de l'API. Le quota par défaut, qui est susceptible de changer, nous aide à optimiser les allocations de quota et à faire évoluer notre infrastructure d'une manière plus significative pour les utilisateurs de l'API. Vous pouvez consulter votre utilisation du quota sur la page Quotas de la console d'API.

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

Calculer l'utilisation du quota

Google calcule votre utilisation du quota en attribuant un coût à chaque requête. Les coûts varient en fonction du type d'opération. 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.
  • Une importation de vidéos coûte 1600 unités.

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

Ressources partielles

L'API permet, et même nécessite, la récupération de ressources partielles pour que les applications évitent le transfert, l'analyse et le stockage de données inutiles. Cette approche permet également à l'API d'utiliser plus efficacement les ressources réseau, CPU et de mémoire.

L'API accepte deux paramètres de requête, décrits 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 à 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 la 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) à inclure dans une réponse de l'API. Par exemple, une ressource video comprend les é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. Vous pouvez les considérer comme des groupes de champs de métadonnées que le serveur d'API peut (ou ne peut pas) récupérer. Par conséquent, le paramètre part vous demande de sélectionner les composants de ressources que votre application utilise réellement. Cette exigence remplit deux objectifs clés:

  • Elle réduit la latence en empêchant le serveur d'API de perdre du temps à 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 pourrait 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 plus 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, afin que la réponse n'inclue qu'un ensemble spécifique de champs. Le paramètre fields vous permet de supprimer des propriétés imbriquées d'une réponse de l'API et ainsi de réduire 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 repose librement 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=*) 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 à 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 de l'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 garantir 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 comprenant quatre parties, ainsi que les propriétés kind et etag.
  2. L'exemple 2 renvoie une ressource vidéo comprenant deux parties, ainsi que les propriétés kind et etag.
  3. L'exemple 3 renvoie une ressource vidéo comprenant deux parties, mais exclut les propriétés kind et etag.
  4. L'exemple 4 renvoie une ressource vidéo comprenant 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 des ressources d'API et leurs ETags. 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) pour indiquer 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.

    Les bibliothèques clientes pour les API Google diffèrent dans leur compatibilité avec les ETag. Par exemple, la bibliothèque cliente JavaScript accepte les ETag via une liste blanche pour les en-têtes de requête autorisés, qui incluent 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 ETags.

  • Protection contre les remplacements involontaires de modifications : les ETags permettent de s'assurer que plusieurs clients API n'écrasent pas les modifications des autres par inadvertance. Lors de la mise à jour ou de la suppression d'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.

Utiliser des ETag dans votre application présente plusieurs avantages:

  • L'API répond plus rapidement aux requêtes de ressources mises en cache mais non modifiées, ce qui permet de réduire la latence et l'utilisation de la bande passante.
  • Votre application ne remplacera pas par inadvertance les modifications d'une ressource effectuées à partir d'un autre client API.

Google APIs Client Library for JavaScript accepte les en-têtes de requêtes HTTP If-Match et If-None-Match, ce qui permet aux ETag de fonctionner dans le contexte d'une 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 plus de temps CPU pour décompresser les réponses de l'API, le fait de consommer moins de ressources réseau compense généralement ce coût.

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

  • 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 conditions requises pour activer la compression gzip:

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