Cette page présente des exemples de requêtes envoyées à l'API YouTube Data. L'API YouTube Data permet de récupérer et de manipuler des ressources YouTube telles que les vidéos, les chaînes et les playlists. Chaque exemple est associé à Google APIs Explorer et renseigne ce dernier afin que vous puissiez l'exécuter et voir la réponse.
Pour savoir comment mettre en ligne du contenu à l'aide de l'API YouTube Data, consultez Importations avec reprise.
Présentation
Pour plus de clarté, les exemples de cette page montrent les éléments caractéristiques de chaque requête et abrégés l'URL de base de l'hôte qui traite les requêtes de l'API Data (https://www.googleapis.com/youtube/v3). Pour envoyer la demande 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 demandes récupèrent des données qui ne sont accessibles qu'au propriétaire de la chaîne YouTube, comme la liste des abonnés. Ces demandes nécessitent que le propriétaire de la chaîne accorde à Google APIs Explorer le droit d'exécuter les requêtes API YouTube Data en son nom. Pour plus d'informations sur l'autorisation d'accès aux données du canal privé, consultez l'article Implémenter l'authentification OAuth 2.0. Après avoir associé APIs Explorer, cliquez sur le bouton Authorize requests using OAuth 2.0 (Autoriser les requêtes à l'aide d'OAuth 2.0). Cette étape autorise APIs Explorer à envoyer 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 qu'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 qui sont incluses dans la réponse. Le paramètre identifie une ou plusieurs propriétés de ressources de niveau supérieur (non imbriquées) à inclure dans la réponse. Par exemple, voici certaines 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, 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.Pour en savoir plus, consultez Premiers pas avec l'API YouTube Data.
Récupérer les informations de la 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 canal et le paramètre contentDetails correspondant à la chaîne de l'utilisateur authentifié. Le fichier contentDetails contient les différentes playlists générées par le système qui sont associées à la chaîne. De nombreuses requêtes ultérieures 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, vous devez rechercher les "mises en ligne" playlist renvoyée dans la réponse ci-dessus concernant les informations sur la chaîne, à l'aide de 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 de playlist. L'ID vidéo de l'élément de la playlist est videoId dans la partie contentDetails.
Vous pouvez récupérer les favoris, les "J'aime", l'historique des vidéos regardées ou les listes "À regarder plus tard" d'un utilisateur à l'aide de la demande ci-dessus en remplaçant l'ID de playlist correspondant dans la réponse contenant les informations de la chaîne.
Playlists créées par les utilisateurs
Cette requête utilise la méthode playlists.list pour récupérer les playlists associées à la chaîne authentifiée. Sachez que cette demande ne permet pas de récupérer les playlists générées par le système qui figurent dans les informations de la chaîne (vidéos mises en ligne, historique des vidéos regardées, etc.). Seules les playlists créées par les utilisateurs sont récupérées.
GET {base_URL}/playlists?part=snippet &mine=true
Une fois que vous disposez de l'ID d'une playlist, vous pouvez récupérer ses éléments à l'aide de la demande indiqué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 à l'origine de la requête. Par exemple, cette demande récupère les playlists associées à la chaîne Google Developers.
GET {base_URL}/playlists?part=snippet &channelId=UC_x5XG1OV2P6uZZ5FSM9Ttw &key={YOUR_API_KEY}
Récupérer les 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 à une chaîne particulière ou les abonnements d'un utilisateur particulier, en fonction des 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 à la chaîne authentifiée.
GET {base_URL}/subscriptions?part=snippet &mySubscribers=true
Abonnements des utilisateurs
La même méthode que celle listant les abonnés (subscriptions.list) peut être utilisée pour répertorier 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é des utilisateurs
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 à un canal 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 spécifique, aux abonnements de l'utilisateur ou à sa page d'accueil YouTube personnalisée.
Activité au cours d'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 demande récupère le flux d'activité personnalisée qui s'affiche sur la page d'accueil YouTube de l'utilisateur authentifié.
GET {base_URL}/activities?part=snippet,contentDetails &home=true
L'API YouTube Analytics permet d'obtenir des statistiques de visionnage, des indicateurs de popularité et des données démographiques pour les vidéos et les chaînes YouTube. La page Exemples de requêtes API indique comment récupérer les rapports standards de YouTube Analytics.
Rechercher
La méthode search.list vous permet de rechercher des vidéos, des chaînes ou des playlists YouTube correspondant à certains critères. Vous pouvez effectuer une recherche en fonction des propriétés, des mots clés ou des thèmes de la vidéo (ou une combinaison de ces critères), et 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. Cependant, contrairement à d'autres ressources YouTube, un résultat de recherche n'est pas un objet persistant avec un identifiant unique.
De nombreuses requêtes recherchent des contenus accessibles 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 "my" vidéos. Lorsque vous envoyez une requête non authentifiée, vous devez inclure l'argument key qui spécifie la clé API unique de votre application.
Mes vidéos les plus regardées
Cette requête récupère toute la vidéo de l'utilisateur authentifié et la classe dans l'ordre décroissant 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 ayant des propriétés particulières, à savoir des vidéos haute définition pouvant être intégrées sur d'autres sites. Il répertorie les résultats par ordre décroissant de 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 mot clé pour rechercher des vidéos sur l'API YouTube Data comportant des sous-titres.
GET {base_URL}/search?part=snippet &q=YouTube+Data+API &type=video &videoCaption=closedCaption &key={YOUR_API_KEY}
Recherche basée sur un thème
Une méthode plus sophistiquée pour rechercher des vidéos sur un sujet particulier consiste à utiliser des sujets Freebase plutôt que des mots clés. Les ressources vidéo et de chaîne YouTube contiennent toutes un objet topicDetails qui contient une liste d'ID de sujets Freebase associés à la ressource. Une recherche par thème est plus intelligente qu'une recherche par mot clé, car un sujet 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 sujet Freebase, vous devez d'abord récupérer l'ID du sujet à l'aide de l'API Freebase. Cette requête renvoie les vidéos associées au sujet Freebase pour Python, dont l'ID de sujet 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 demande 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, il vous suffit de modifier le paramètre type.
GET {base_URL}/search?part=snippet &q=soccer &type=channel &key={YOUR_API_KEY}
Si vous souhaitez afficher tous les contenus relatifs 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 les contenus de tous les types.
GET {base_URL}/search?part=snippet &q=soccer &key={YOUR_API_KEY}
Créer et mettre à jour des ressources
Toutes les demandes que nous avons examinées utilisent la méthode HTTP GET pour récupérer des données YouTube. L'API YouTube Data propose également des méthodes qui utilisent la méthode 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 Google Developers. En d'autres termes, il 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 demande 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 demande 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 } }