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
-
Vous devez disposer d'un compte Google pour accéder à la console Google APIs, demander une clé API et enregistrer votre application.
-
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.
-
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:
- Accédez à la console API et sélectionnez le projet que vous venez d'enregistrer.
- 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é.
-
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.
-
Sélectionnez une bibliothèque cliente pour faciliter la mise en œuvre de votre API.
-
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:
- L'exemple 1 renvoie une ressource vidéo comprenant quatre parties, ainsi que les propriétés
kind
etetag
. - L'exemple 2 renvoie une ressource vidéo comprenant deux parties, ainsi que les propriétés
kind
etetag
. - L'exemple 3 renvoie une ressource vidéo qui comprend deux parties, mais exclut les propriétés
kind
etetag
. - L'exemple 4 renvoie une ressource vidéo qui comprend deux parties, mais exclut
kind
etetag
, ainsi que certaines propriétés imbriquées dans l'objetsnippet
de la ressource.
URL: https://www.googleapis.com/youtube/v3/videos?id=7lCDEYXw3mM&key=YOUR_API_KEY
&part=snippet,contentDetails,statistics,status Description: This example retrieves avideo
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 thepart
parameter value so that thecontentDetails
andstatus
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 thefields
parameter to remove allkind
andetag
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 thefields
parameter from example 3 so that in the API response, each video resource'ssnippet
object only includes thechannelId
,title
, andcategoryId
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
etIf-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
surgzip
. - 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)