Implémentation: vidéos

Les exemples suivants montrent comment utiliser l'API YouTube Data (v3) pour effectuer des fonctions liées aux vidéos.

Récupérer les vidéos mises en ligne d'une chaîne

Cet exemple récupère les vidéos mises en ligne sur une chaîne spécifique. Il comporte deux étapes :

Cet exemple montre comment récupérer une liste des vidéos les plus populaires sur YouTube, qui sont sélectionnées à l'aide d'un algorithme combinant de nombreux signaux différents pour déterminer la popularité globale.

Pour récupérer la liste des vidéos les plus populaires, appelez la méthode videos.list et définissez la valeur du paramètre chart sur mostPopular. Le classement mostPopular inclut les vidéos musicales, les films et les vidéos de gaming tendances.

Vous pouvez ensuite définir les paramètres suivants :

  • regionCode : indique à l'API de renvoyer une liste de vidéos pour la région spécifiée. La valeur de paramètre est un code pays ISO 3166-1 alpha-2. Vous pouvez utiliser la méthode i18nRegions.list pour récupérer la liste des codes de région compatibles avec YouTube.
  • videoCategoryId : identifie la catégorie de vidéo pour laquelle les vidéos les plus populaires doivent être récupérées. Vous pouvez utiliser la méthode videoCategories.list pour récupérer la liste des ID de catégorie compatibles avec YouTube.

Par exemple, la requête suivante récupère les vidéos de sport les plus populaires en Espagne :

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

Récupérer les statistiques de plusieurs vidéos

Cet exemple récupère les statistiques d'une liste de vidéos à l'aide de la méthode videos.batchGetStats.

Pour utiliser cette méthode, définissez le paramètre id de la requête sur une liste d'ID de vidéos YouTube séparés par une virgule pour lesquels vous souhaitez récupérer des statistiques. Définissez la valeur du paramètre part sur une liste séparée par une virgule des parties de la ressource videoStat que vous souhaitez inclure dans la réponse. Les parties compatibles sont snippet, statistics, contentDetails et id.

L'authentification est requise pour utiliser cette méthode sur des vidéos non publiques, mais pas pour les vidéos publiques. Si la requête récupère des données pour des vidéos non publiques, elle doit être correctement autorisée.

La requête ci-dessous récupère les statistiques des ID de vidéo VIDEO_ID_1 et VIDEO_ID_2 :

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

Mettre en ligne une vidéo

Comme l'API Explorer ne permet pas d'importer des fichiers, cette description ne renvoie pas à un exemple exécutable. Les ressources suivantes vous aideront à modifier votre application afin qu'elle puisse mettre en ligne des vidéos à l'aide de l'API v3 :

  • La documentation de la méthode videos.insert de l'API contient plusieurs exemples de code qui expliquent comment mettre en ligne une vidéo à l'aide de différents langages de programmation.

  • Le guide sur les importations avec reprise explique la séquence de requêtes HTTP qu'une application utilise pour mettre en ligne des vidéos à l'aide d'un processus d'importation avec reprise. Ce guide est principalement destiné aux développeurs qui ne peuvent pas utiliser les bibliothèques clientes des API Google, dont certaines offrent une compatibilité native avec les importations avec reprise.

  • L'exemple JavaScript pour mettre en ligne une vidéo utilise le partage de ressources interorigines (CORS) pour montrer comment importer un fichier vidéo via une page Web. La bibliothèque d'importation CORS utilisée par l'API v3 est naturellement compatible avec l'importation avec reprise. De plus, l'exemple montre comment vérifier l'état d'une vidéo mise en ligne en récupérant la partie processingDetails de la ressource video, ainsi que comment gérer les changements d'état de la vidéo mise en ligne.

Vérifier l'état d'une vidéo mise en ligne

Cet exemple montre comment vérifier l'état d'une vidéo mise en ligne. Une vidéo mise en ligne est immédiatement visible dans le flux des vidéos mises en ligne de l'utilisateur authentifié. Toutefois, elle ne sera visible sur YouTube qu'une fois traitée.

  • Étape 1 : Mettre en ligne la vidéo

    Appelez la méthode videos.insert pour mettre en ligne la vidéo. Si la requête aboutit, la réponse de l'API contient une ressource video qui identifie l'ID vidéo unique de la vidéo mise en ligne.

  • Étape 2 : Vérifier l'état de la vidéo

    Appelez la méthode videos.list pour vérifier l'état de la vidéo. Définissez la valeur du paramètre id sur l'ID vidéo obtenu à l'étape 1. Définissez la valeur du paramètre part sur processingDetails.

    Si la requête est traitée correctement, la réponse de l'API contient une ressource video. Vérifiez la valeur de la propriété processingDetails.processingStatus pour déterminer si YouTube est toujours en train de traiter la vidéo. La valeur de la propriété passera à une valeur autre que processing, telle que succeeded ou failed, lorsque YouTube aura terminé le traitement de la vidéo.

    Le corps de la requête est une ressource video dans laquelle la propriété id spécifie l'ID vidéo de la vidéo que vous supprimez. Dans cet exemple, la ressource contient également un objet recordingDetails.

    La requête ci-dessous vérifie l'état d'une vidéo. Pour exécuter la requête dans l'API Explorer, vous devez définir la valeur de la propriété id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID

Remarque : Votre application peut interroger l'API pour vérifier régulièrement l'état d'une vidéo récemment mise en ligne. Une fois la vidéo traitée, votre application peut créer un bulletin ou effectuer une autre action en fonction de l'état de la vidéo.

Mettre à jour une vidéo

Cet exemple montre comment mettre à jour une vidéo pour ajouter des informations sur l'heure et le lieu où elle a été enregistrée. Il comporte les étapes suivantes :

  • Étape 1 : Récupérer l'ID de la vidéo

    Suivez les étapes ci-dessus pour récupérer les vidéos mises en ligne pour la chaîne de l'utilisateur actuellement authentifié. La liste peut être utilisée pour afficher une liste de vidéos, en utilisant l'ID de chaque vidéo comme clé.

    Remarque : Il existe de nombreuses autres façons d'obtenir des ID vidéo, par exemple en récupérant des résultats de recherche ou en listant des éléments dans une playlist. Toutefois, comme une vidéo ne peut être mise à jour que par son propriétaire, la récupération d'une liste de vidéos appartenant à l'utilisateur qui autorise la requête API est une première étape probable de ce processus.

  • Étape 2 : Mettre à jour une vidéo

    Appelez la méthode videos.update pour mettre à jour une vidéo spécifique. Définissez la valeur du paramètre part sur recordingDetails. (La valeur du paramètre dépend des champs de métadonnées de la vidéo qui sont mis à jour.)

    Le corps de la requête est une ressource video dans laquelle la propriété id spécifie l'ID vidéo de la vidéo que vous mettez à jour. Dans cet exemple, la ressource contient également un objet recordingDetails.

    L'exemple de ressource ci-dessous indique que la vidéo a été enregistrée le 30 octobre 2013 à Boston :

    {
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}

    Pour exécuter la requête dans l'API Explorer, vous devez définir la valeur de la propriété id.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

L'accès des marques partenaires à l'initiative des créateurs (CI BPA) permet au propriétaire d'une vidéo de partager l'accès à sa vidéo avec la chaîne d'une marque partenaire. Cela nécessite la partie brandPartner.

Établir l'accès (insertion)

Pour établir l'accès lors de la mise en ligne d'une vidéo, incluez brandPartner dans le paramètre part et fournissez un objet brandPartner dans le corps de la requête. Vous devez spécifier channelId (ID de chaîne externe commençant par "UC") ou channelHandle (commençant par "@") pour identifier la chaîne de la marque.

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

Seul le channelId résolu sera renvoyé dans la réponse.

Mettre à jour ou supprimer l'accès (mise à jour)

Pour mettre à jour l'accès à une autre chaîne de marque ou pour supprimer l'accès, appelez la méthode videos.update avec brandPartner dans le paramètre part.

Pour remplacer l'accès, fournissez le nouveau channelId ou channelHandle dans le corps de la requête :

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

Pour supprimer l'accès, envoyez une requête avec brandPartner dans le paramètre part, mais avec un objet brandPartner vide dans le corps de la requête :

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

Mettre en ligne une miniature personnalisée et la définir pour une vidéo

Vous pouvez utiliser la méthode thumbnails.set de l'API v3 pour mettre en ligne une miniature personnalisée et la définir pour une vidéo. Dans votre requête, la valeur du paramètre videoId identifie la vidéo pour laquelle la miniature sera utilisée.

Cette requête ne peut pas être testée à l'aide de l'API Explorer, car celui-ci ne permet pas d'importer des fichiers multimédias, ce qui est une exigence pour cette méthode.

Exemples de code associés : PHP, Python

Supprimer une vidéo

Cet exemple montre comment supprimer une vidéo. Il comporte les étapes suivantes :

  • Étape 1 : Récupérer l'ID de la vidéo

    Suivez les étapes ci-dessus pour récupérer les vidéos mises en ligne pour la chaîne de l'utilisateur actuellement authentifié. La liste peut être utilisée pour afficher une liste de vidéos, en utilisant l'ID de chaque vidéo comme clé.

    Remarque : Il existe de nombreuses autres façons d'obtenir des ID vidéo, par exemple en récupérant des résultats de recherche ou en listant des éléments dans une playlist. Toutefois, comme une vidéo ne peut être supprimée que par son propriétaire, la récupération d'une liste de vidéos appartenant à l'utilisateur qui autorise la requête API est une première étape probable de ce processus.

  • Étape 2 : Supprimer une vidéo

    Appelez la méthode videos.delete pour supprimer une vidéo spécifique. Dans la requête, le paramètre id spécifie l'ID vidéo de la vidéo que vous supprimez. La requête doit être autorisée à l'aide d'OAuth 2.0. Si vous testez cette requête dans l'API Explorer, vous devrez remplacer la valeur du paramètre id par un ID de vidéo valide.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID

Signaler une vidéo abusive

Cet exemple montre comment signaler une vidéo contenant du contenu abusif. Il comporte les étapes suivantes :

  • Étape 1 : Récupérer les ID expliquant pourquoi la vidéo est signalée

    Envoyez une requête autorisée à la méthode videoAbuseReportReasons.list pour récupérer la liste des motifs valides pour signaler une vidéo. L'exemple de ressource videoAbuseReportReason ci-dessous contient des informations permettant de signaler une vidéo contenant du spam ou du contenu trompeur.

    {
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

    Comme indiqué dans la ressource, ce motif est associé à une liste de motifs secondaires. Lorsque vous signalez une vidéo pour spam, vous devez fournir l'ID du motif et nous vous recommandons vivement de fournir également un motif secondaire.

  • Étape 2 : Signaler la vidéo pour contenu abusif

    Envoyez une requête autorisée à la méthode videos.reportAbuse pour signaler la vidéo. Le corps de la requête est un objet JSON qui identifie à la fois la vidéo signalée et le motif de son signalement. Comme indiqué à l'étape 1, pour certains types de motifs, un motif secondaire est accepté et fortement recommandé.

    La propriété videoId de l'objet JSON identifie la vidéo signalée.

    L'exemple d'objet JSON ci-dessous signale une vidéo pour spam ou contenu trompeur, et plus précisément pour l'utilisation d'une miniature trompeuse. Comme indiqué dans l'exemple d'objet JSON ci-dessus, l'ID du contenu spam ou trompeur est S. L'ID d'une miniature trompeuse est 28.

    {
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}

    La requête videos.reportAbuse doit être autorisée à l'aide d'OAuth 2.0. Le lien ci-dessous charge l'objet JSON ci-dessus dans l'API Explorer. Pour tester la requête, vous devez remplacer la valeur de la propriété videoId par un ID de vidéo valide. N'oubliez pas que l'envoi de cette requête signalera la vidéo.

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse