Exemples de requêtes API

Vous trouverez sur cette page des exemples de requêtes envoyées à l'API YouTube Data. Vous pouvez utiliser 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 contient un lien vers l'explorateur d'API Google et l'alimente pour vous permettre d'exécuter l'exemple et d'obtenir la réponse.

Pour en savoir plus sur la mise en ligne de contenus à l'aide de l'API YouTube Data, consultez la page Importations avec reprise.

Présentation

Pour plus de clarté, les exemples de cette page présentent les éléments distinctifs de chaque requête et abrègent l'URL de base de l'hôte qui traite les requêtes API de données (https://www.googleapis.com/youtube/v3). Pour envoyer la requête en dehors du contexte des exemples, vous devez inclure l'URL complète.

Voici un exemple de requête telle qu'elle 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 d'entre elles récupèrent des données accessibles uniquement au propriétaire de la chaîne YouTube, telles que la liste des abonnés. Ces demandes nécessitent que le propriétaire de la chaîne accorde à l'explorateur des API Google le droit d'effectuer des demandes de l'API YouTube Data en son nom. Pour en savoir plus sur l'autorisation d'accès aux données d'une chaîne privée, consultez l'article Mise en œuvre de l'authentification OAuth 2.0. Après avoir associé l'explorateur d'API, 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 que l'explorateur d'API 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 premier niveau (non imbriquées) à inclure dans la réponse. Voici quelques exemples d'éléments d'une ressource vidéo:

  • extrait [context sensitive]
  • détailsDétails
  • joueur
  • statistics
  • état

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.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 les détails des canaux 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 l'ID de la chaîne (contentDetails) de l'utilisateur authentifié. Les contentDetails incluent les différentes playlists générées par le système associées à la chaîne. De nombreuses 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 "Vidéos mises en ligne" renvoyée dans la réponse ci-dessus concernant les informations de la chaîne, en utilisant 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 l'explorateur des API Google, remplacez {UPLOADS_PLAYLIST_ID} par l'ID de la 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 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 vidéos à regarder plus tard à l'aide de la requête ci-dessus en remplaçant l'ID de playlist correspondant de la réponse contenant les informations sur 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 récupère pas les playlists générées par le système qui sont fournies dans les informations de la chaîne (vidéos mises en ligne, watchHistory, etc.). Il récupère uniquement les playlists créées par les utilisateurs.

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 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 qui effectue 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 des abonnements

Une ressource subscription définit une relation entre un utilisateur YouTube (l'abonné) et une chaîne. La méthode subscriptions.list permet de récupérer les abonnés à une chaîne spécifique ou les abonnements d'un utilisateur donné, 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 utilisateur

La même méthode permet de répertorier les abonnés (subscriptions.list) pour lister les chaînes auxquelles un utilisateur s'abonne. Cette requête utilise le paramètre mine pour récupérer la liste des chaînes YouTube auxquelles l'utilisateur authentifié s'est abonné.

GET {base_URL}/subscriptions?part=snippet
                            &mine=true

Récupérer l'activité des utilisateurs

Une ressource activity contient des informations sur les actions effectuées par une chaîne ou un utilisateur spécifique 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 particulière, aux abonnements de l'utilisateur ou à sa page d'accueil YouTube personnalisée.

Activité sur une période donnée

Cette requête récupère toutes les actions que l'utilisateur authentifié a effectuées 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 obtenir des statistiques de visionnage, des statistiques sur la popularité et des données démographiques concernant vos vidéos et chaînes YouTube, vous pouvez utiliser l'API YouTube Analytics. La page Exemples de requêtes API indique comment récupérer des rapports courants depuis YouTube Analytics.

La méthode search.list vous permet de rechercher des vidéos, des chaînes ou des playlists YouTube qui correspondent aux critères spécifiés. Vous pouvez effectuer une recherche en fonction des propriétés de la vidéo, des mots clés ou des thèmes (ou une combinaison des deux), 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. Cependant, contrairement à d'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 requiert une authentification, car il demande spécifiquement "mes" vidéos. Lorsque vous envoyez une requête non authentifiée, vous devez inclure l'argument key qui spécifie la clé API unique pour 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 répertorie 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 ayant des propriétés particulières, à savoir des vidéos haute définition qui peuvent être intégrées à d'autres sites. Les résultats sont classés par ordre décroissant de classification.

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 permet de rechercher des vidéos sous-titrées dans l'API YouTube Data.

GET {base_URL}/search?part=snippet
                     &q=YouTube+Data+API
                     &type=video
                     &videoCaption=closedCaption
                     &key={YOUR_API_KEY}

Recherche par thème

Une méthode plus sophistiquée de recherche de vidéos sur un sujet particulier consiste à utiliser les 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 thématique est plus intelligente qu'une recherche par mot clé, car un sujet Freebase représente tous les aspects d'un concept ou d'un élément 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 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 des playlists correspondant au mot clé "football".

GET {base_URL}/search?part=snippet
                     &q=soccer
                     &type=playlist
                     &key={YOUR_API_KEY}

Si vous préférez rechercher 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 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 du contenu de tous 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 les 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 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

L'utilisateur authentifié est alors abonné à 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, nous allons y ajouter 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
      }
   }