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 prises en charge par 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 afin 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 pour lesquels votre application est autorisée à utiliser:

    1. Accédez à la console API et 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 fondamentaux du format de données JSON (JavaScript Object Notation). JSON est un format de données commun, 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 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 concernant une action effectuée par un utilisateur sur le site YouTube. Les actions de l'utilisateur 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 aux favoris ou la publication d'un bulletin de 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 en tant qu'image de 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 d'une chaîne, 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 leur popularité. Les catégories de guide visent à organiser les chaînes de sorte à permettre aux utilisateurs de YouTube de trouver plus facilement le contenu qu'ils recherchent. Bien qu'une chaîne puisse être associée à une ou plusieurs catégories de guides, il n'est pas garanti qu'elles appartiennent à l'une ou l'autre des catégories de guides.
i18nLanguage Identifie une langue d'application acceptée par le site Web YouTube. Le langage de l'application peut également être appelé langage d'interface utilisateur.
i18nRegion Définit une zone géographique qu'un utilisateur YouTube peut sélectionner comme zone de contenu préférée. La zone de contenu est également 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 de manière séquentielle et partagées avec d'autres utilisateurs.
playlistItem Identifie une ressource, telle qu'une vidéo, faisant 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 correspondant aux paramètres de recherche spécifiés dans une requête API. Bien qu'un résultat de recherche renvoie vers une ressource identifiable de manière unique, comme 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 permet d'informer l'utilisateur lorsque de nouvelles vidéos sont ajoutées à une chaîne ou lorsqu'un autre utilisateur effectue l'une des actions disponibles sur YouTube, comme mettre en ligne une vidéo, la noter ou ajouter un commentaire sur une vidéo.
thumbnail Identifie les vignettes associées à une ressource.
video Représente une vidéo YouTube unique.
videoCategory Identifie une catégorie qui a été ou pourrait être associée aux vidéos mises en ligne.
watermark Identifie une image qui s'affiche pendant 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 renvoie, ainsi que des informations temporelles qui déterminent à quel moment le filigrane apparaît pendant la lecture de la vidéo 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. Autre exemple : un résultat de recherche contient une propriété videoId, playlistId ou channelId qui identifie une ressource vidéo, playlist ou de chaîne spécifique.

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 effectuent des fonctions plus spécifiques à ces ressources. Par exemple, la méthode videos.rate associe la note d'un utilisateur à 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 des données dans votre requête.
delete Supprime (DELETE) une ressource spécifique.

L'API est actuellement compatible avec des méthodes permettant de répertorier chacun des types de ressources pris en charge, ainsi qu'à des opérations d'écriture pour de nombreuses ressources.

Le tableau ci-dessous présente les opérations compatibles avec différents types de ressources. Les opérations qui insèrent, mettent à jour ou suppriment des ressources nécessitent toujours une autorisation de l'utilisateur. Dans certains cas, les méthodes list prennent en charge les requêtes autorisées et non autorisées. Les requêtes non autorisées ne récupèrent que des 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

Le 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 d'autres personnes. Toutes les requêtes API, y compris les requêtes non valides, entraînent au moins un coût pour le quota. Vous trouverez le quota disponible pour votre application dans API Console.

Le quota par défaut des projets pour lesquels l'API YouTube Data est activé est de 10 000 unités par jour, ce qui est suffisant pour la grande majorité des utilisateurs de notre API. Le quota par défaut, susceptible d'être modifié, nous aide à optimiser les allocations et à faire évoluer notre infrastructure de manière 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 un quota supplémentaire en en terminant la extension de quota formulaire de demande 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. Différents types de les opérations ont des coûts de quota différents. Exemple :

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

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

Ressources partielles

L'API permet, et exige de récupérer une partie des ressources, afin que les applications évitent le transfert, l'analyse et le stockage de 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, qui sont 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 à 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. Ce paramètre identifie une ou plusieurs propriétés de ressources de niveau supérieur (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, avec le paramètre part, vous devez sélectionner les composants de ressources que votre application utilise réellement. Cette exigence a deux fonctions principales:

  • Il 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.
  • Il réduit l'utilisation de la bande passante en réduisant (ou en éliminant) la quantité de données inutiles que votre application est susceptible de récupérer.

Au fil du temps, à mesure que les ressources ajouteront des éléments, ces avantages ne feront qu'augmenter, car votre application ne demandera plus de nouvelles propriétés non compatibles.

Utiliser le paramètre fields

Le paramètre fields filtre la réponse de l'API, qui ne contient que les parties de ressources 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 dans une réponse.)

Les règles suivantes décrivent 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=*) 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 à 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 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 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.
<ph type="x-smartling-placeholder">
</ph> <ph type="x-smartling-placeholder">
</ph>
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"
   }
  }
 ]
}
<ph type="x-smartling-placeholder">
</ph>
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"
   }
  }
 ]
}
<ph type="x-smartling-placeholder">
</ph>
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"
   }
  }
 ]
}
<ph type="x-smartling-placeholder">
</ph>
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 donnée. La ressource peut être un flux entier ou un article 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 de l'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 été modifiée, l'API renvoie une réponse HTTP 304 (Not Modified), 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 prennent pas en charge les ETag. Par exemple, la bibliothèque cliente JavaScript prend en charge les ETags via une liste blanche pour les en-têtes de requête autorisés, y compris 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é, la ressource peut être diffusée à partir du cache du navigateur. En revanche, le client Obj-C ne prend pas en charge les ETag.

  • Protection contre les écrasements involontaires des modifications : les ETag permettent de s'assurer que plusieurs clients API n'écrasent pas involontairement les modifications apportées par d'autres. 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.

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

  • L'API répond plus rapidement aux requêtes portant sur des ressources mises en cache, mais inchangé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 apportées à une ressource à 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 nécessaire pour chaque réponse de l'API en activant la compression gzip. Bien que votre application nécessite un temps CPU supplémentaire pour décompresser les réponses de l'API, l'avantage d'une consommation moins importante des ressources réseau compense généralement 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)