Cette page présente des exemples de requêtes adressées à l'API YouTube Data. Vous utilisez l'API YouTube Data pour récupérer et manipuler des ressources YouTube telles que des vidéos, des chaînes et des playlists. Chaque exemple renvoie à Google APIs Explorer et le remplit afin que vous puissiez l'exécuter et voir la réponse.
Pour en savoir plus sur la mise en ligne de contenu à l'aide de l'API YouTube Data, consultez Importations avec reprise.
Présentation
Pour plus de clarté, les exemples de cette page présentent les éléments distinctifs de chaque requête API et abrègent l'URL de base de l'hôte qui traite les requêtes de l'API Data (https://www.googleapis.com/youtube/v3). Pour effectuer la requête en dehors du contexte des exemples, vous devez inclure l'URL complète.
Voici un exemple de requête tel qu'il apparaît sur cette page :
GET {base-URL}/channels?part=contentDetails &mine=true
L'URL complète de cette requête est la suivante :
GET https://www.googleapis.com/youtube/v3/channels?part=contentDetails &mine=true
Plusieurs requêtes récupèrent des données accessibles uniquement au propriétaire de la chaîne YouTube, comme la liste des abonnés. Ces requêtes nécessitent que le propriétaire de la chaîne autorise Google APIs Explorer à effectuer des requêtes d'API YouTube Data en son nom. (Pour en savoir plus sur l'autorisation d'accès aux données privées d'une chaîne, consultez Implémenter l'authentification OAuth 2.0.) Après avoir cliqué sur le lien vers APIs Explorer, cliquez sur le bouton Autoriser les requêtes à l'aide d'OAuth 2.0. Cette étape autorise APIs Explorer à effectuer des requêtes au nom du propriétaire. Vous sélectionnez également le champ d'application de l'autorisation, qui spécifie les types de requêtes que APIs Explorer peut effectuer.
La réponse à chaque requête est la représentation JSON d'une ressource YouTube. Le paramètre part de la requête spécifie les parties de la ressource incluses dans la réponse. Le paramètre identifie une ou plusieurs propriétés de ressource de premier niveau (non imbriquées) qui doivent être incluses dans la réponse. Par exemple, voici quelques-unes des parties d'une ressource vidéo :
- extrait [context sensitive]
- contentDetails
- joueur
- statistics
- état
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 la ressource que votre application utilise réellement.Pour en savoir plus, consultez Premiers pas avec l'API YouTube Data.
Récupérer des informations sur une chaîne
Cette requête utilise la méthode channels.list pour récupérer des informations sur les chaînes appartenant à l'utilisateur authentifié.
GET {base_URL}/channels?part=contentDetails &mine=true
La réponse à cette requête inclut l'ID de la chaîne et les contentDetails de la chaîne de l'utilisateur authentifié. Les contentDetails incluent les différentes playlists générées par le système associées à la chaîne. La plupart des requêtes suivantes nécessitent l'ID de la chaîne ou l'un des ID de playlist. Il est donc important de les enregistrer.
{
"id": {CHANNEL_ID},
"kind": "youtube#channel",
"etag": etag,
"contentDetails": {
"relatedPlaylists": {
"likes": {LIKES_PLAYLIST_ID},
"favorites": {FAVORITES_PLAYLIST_ID},
"uploads": {UPLOADS_PLAYLIST_ID},
"watchHistory": {WATCHHISTORY_PLAYLIST_ID},
"watchLater": {WATCHLATER_PLAYLIST_ID}
},
"googlePlusUserId": string
},
}Vidéos mises en ligne et playlists générées par le système
YouTube ajoute toutes les vidéos mises en ligne à une playlist associée à la chaîne. Pour obtenir la liste des vidéos mises en ligne, interrogez la playlist "uploads" renvoyée dans la réponse affichée ci-dessus pour obtenir des informations sur la chaîne. Utilisez la méthode playlistItems.list pour récupérer les vidéos de cette playlist.
Avant d'exécuter l'exemple de requête suivant dans Google APIs Explorer, remplacez {UPLOADS_PLAYLIST_ID} par l'ID de playlist de la requête précédente.
GET {base_URL}/playlistItems?part=contentDetails &playlistId={UPLOADS_PLAYLIST_ID}
Notez que la valeur "id" de chaque élément renvoyé correspond à son ID playlistItem. L'ID vidéo de l'élément de playlist est le videoId dans la partie contentDetails.
Vous pouvez récupérer les playlists "Favoris", "J'aime", "Historique des vidéos regardées" ou "À regarder plus tard" d'un utilisateur à l'aide de la requête ci-dessus en remplaçant l'ID de playlist correspondant dans la réponse d'informations sur la chaîne.
Playlists créées par l'utilisateur
Cette requête utilise la méthode playlists.list pour récupérer les playlists associées à la chaîne authentifiée. Notez que cette requête ne récupère pas les playlists générées par le système incluses dans les informations sur la chaîne (mises en ligne, historique des vidéos regardées, etc.). Elle ne récupère que les playlists créées par l'utilisateur.
GET {base_URL}/playlists?part=snippet &mine=true
Une fois que vous disposez d'un ID de playlist, vous pouvez récupérer les éléments de la playlist à l'aide de la requête affichée dans la section précédente.
Vous pouvez demander des informations sur les playlists publiques d'une chaîne sans authentification. Lorsque vous envoyez une requête non authentifiée, vous devez inclure l'argument key qui spécifie la clé API unique de l'application qui effectue la requête. Par exemple, cette requête récupère les playlists associées à la chaîne GoogleDevelopers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Récupérer des abonnements
Une ressource subscription définit une relation entre un utilisateur YouTube (l'abonné) et une chaîne. La méthode subscriptions.list récupère les abonnés d'une chaîne particulière ou les abonnements d'un utilisateur particulier, selon les paramètres que vous incluez dans la requête.
Abonnés de la chaîne
Cette requête récupère la liste des abonnés de la chaîne authentifiée.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Abonnements utilisateur
La même méthode qui liste les abonnés (subscriptions.list) peut être utilisée pour lister les chaînes auxquelles un utilisateur est abonné. Cette requête utilise le paramètre mine pour récupérer la liste des chaînes YouTube auxquelles l'utilisateur authentifié est abonné.
GET {base_URL}/subscriptions?part=snippet &mine=true
Récupérer l'activité de l'utilisateur
Une ressource activity contient des informations sur une action effectuée par une chaîne ou un utilisateur sur YouTube (mise en ligne d'une vidéo, abonnement à une chaîne, etc.). La méthode activities.list récupère les actions associées à une chaîne ou à un utilisateur qui correspondent aux critères de la requête. Par exemple, vous pouvez récupérer les actions associées à une chaîne particulière, aux abonnements de l'utilisateur ou à la page d'accueil YouTube personnalisée de l'utilisateur.
Activité sur une période donnée
Cette requête récupère toutes les actions effectuées par l'utilisateur authentifié en avril 2013.
GET {base_URL}/activities?part=snippet,contentDetails &mine=true &publishedAfter=2013-04-01T00%3A00%3A00Z &publishedBefore=2013-05-01T00%3A00%3A00Z
Activité sur la page d'accueil
Cette requête récupère le flux d'activité personnalisé qui s'affiche sur la page d'accueil YouTube de l'utilisateur authentifié.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
Pour récupérer les statistiques de visionnage, les métriques de popularité et les informations démographiques des vidéos et des chaînes YouTube, utilisez l'API YouTube Analytics. La page Exemples de requêtes API explique comment récupérer des rapports courants à partir de YouTube Analytics.
Rechercher
La méthode search.list vous permet de rechercher des vidéos YouTube, des chaînes ou des playlists qui correspondent à des critères spécifiés. Vous pouvez effectuer une recherche en fonction des propriétés, des mots clés ou des thèmes des vidéos (ou une combinaison de ces éléments), et vous pouvez trier les résultats en fonction de facteurs tels que la date de création, le nombre de vues ou la note.
Comme les autres requêtes de l'API YouTube Data, la méthode search.list renvoie la représentation JSON d'une ressource YouTube. Contrairement aux autres ressources YouTube, un résultat de recherche n'est pas un objet persistant avec un ID unique.
De nombreuses requêtes recherchent du contenu accessible au public et ne nécessitent donc pas d'authentification. Parmi les exemples ci-dessous, seul le premier nécessite une authentification, car il demande spécifiquement "mes" vidéos. Lorsque vous envoyez une requête non authentifiée, vous devez inclure l'key argument qui spécifie la clé API unique de votre application.
Mes vidéos les plus regardées
Cette requête récupère toutes les vidéos de l'utilisateur authentifié et les liste par ordre décroissant en fonction du nombre de vues.
GET {base_URL}/search?part=snippet &forMine=true &order=viewCount &type=video
Vidéos haute définition intégrables
Cette requête recherche des vidéos présentant des propriétés particulières, à savoir des vidéos haute définition pouvant être intégrées sur d'autres sites. Elle liste les résultats par ordre décroissant en fonction de la note.
GET {base_URL}/search?part=snippet &order=rating &type=video &videoDefinition=high &videoEmbeddable=true &key={YOUR_API_KEY}
Vidéos sur un sujet particulier
Cette requête effectue une recherche par mots clés de vidéos sur l'API YouTube Data qui incluent des sous-titres.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Recherche par thème
Pour rechercher des vidéos sur un thème particulier de manière plus sophistiquée, utilisez les thèmes Freebase au lieu de mots clés. Les ressources de chaîne et de vidéo YouTube contiennent toutes un objet topicDetails qui contient une liste d'ID de thèmes Freebase associés à la ressource. Une recherche par thème est plus intelligente qu'une recherche par mots clés, car un thème Freebase représente tous les aspects d'un concept ou d'une chose du monde réel.
Pour effectuer une recherche à l'aide d'un thème Freebase, vous devez d'abord récupérer l'ID du thème à l'aide de l'API Freebase. Cette requête renvoie les vidéos associées au thème Freebase pour Python, dont l'ID est /m/05z1_.
GET {base_URL}/search?part=snippet &topicId=/m/05z1_ &type=video &key={YOUR_API_KEY}
Rechercher des playlists ou des chaînes
La recherche ne se limite pas aux vidéos. Vous pouvez également rechercher des playlists ou des chaînes. Cette requête récupère les playlists qui correspondent au mot clé "football".
GET {base_URL}/search?part=snippet &q=soccer &type=playlist &key={YOUR_API_KEY}
Si vous préférez trouver des chaînes de football, modifiez simplement le paramètre type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Si vous souhaitez obtenir tous les contenus liés au football (chaînes, playlists et vidéos), vous pouvez effectuer une recherche universelle. Si vous omettez le paramètre type, la requête récupère le contenu de tous les types.
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Créer et mettre à jour des ressources
Les requêtes que nous avons examinées jusqu'à présent utilisent toutes la méthode HTTP GET pour récupérer des données YouTube. L'API YouTube Data propose également des méthodes qui utilisent HTTP POST pour créer ou mettre à jour des ressources YouTube telles que des vidéos, des playlists ou des chaînes. Les requêtes suivantes fournissent des exemples.
Les méthodes POST incluent un Request body, qui est la représentation JSON de la ressource en cours de création ou de mise à jour. Vous pouvez créer des représentations JSON dans Google APIs Explorer à l'aide d'un outil interactif.
Créer un abonnement
Cette requête abonne l'utilisateur authentifié à la chaîne GoogleDevelopers. En d'autres termes, elle crée une ressource d'abonnement.
POST {base_URL}/subscriptions?part=snippet
Request body: { 'snippet': { 'resourceId': { 'kind': 'youtube#channel', 'channelId': 'UC_x5XG1OV2P6uZZ5FSM9Ttw' } } }
Créer une playlist
Cette requête crée une playlist publique.
POST {base_URL}/playlists?part=snippet
Request body: { 'snippet': { 'title': 'New playlist', 'description': 'Sample playlist for Data API', } }
Ajouter une vidéo à une playlist
Maintenant que nous avons créé une playlist, ajoutons-y une vidéo. Cette requête ajoute une vidéo au début de la playlist ('position': 0).
POST {base_URL}/playlistItems?part=snippet Request body: { 'snippet': { 'playlistId': '{PLAYLIST_ID}', 'resourceId': { 'kind': 'youtube#video', 'videoId': '{VIDEO_ID}' } 'position': 0 } }