Passer de flux XML à l'API Content ID

Remarque:L'API YouTube Content ID est destinée aux partenaires de contenu YouTube. Elle n'est pas accessible à tous les développeurs ni à tous les utilisateurs de YouTube. Si l'API Content ID YouTube ne figure pas dans la liste de la console Google APIs, consultez le Centre d'aide YouTube pour en savoir plus sur le Programme Partenaire YouTube.

Ce guide explique comment les partenaires de contenu YouTube peuvent migrer des flux de contenu XML vers l'API Content ID de YouTube pour intégrer du contenu dans le système de gestion des droits de YouTube.

Présentation

Pour utiliser le système de gestion des droits Content ID de YouTube, vous devez fournir à YouTube les métadonnées, les informations sur la propriété, les paramètres des règles et les supports de référence pour vos éléments.

YouTube propose de nombreuses options pour envoyer les données de vos éléments. Les partenaires qui mettent régulièrement en ligne de nombreux contenus utilisent souvent une méthode d'importation groupée, en spécifiant les informations sur leurs éléments à l'aide du flux DDEX de YouTube ou d'un modèle de feuille de calcul fourni par YouTube. L'API Content ID de YouTube permet également de contrôler plus précisément le processus de mise en ligne.

Avec l'API, vous créez des éléments et d'autres ressources un par un, contrairement au traitement par lot des flux XML et des feuilles de calcul. L'approche individuelle de l'API peut permettre des importations plus rapides et plus fiables. Vous gérez le processus de mise en ligne de manière transactionnelle, en surveillant la réussite des actions individuelles et en réagissant immédiatement en cas de problème. Vous pouvez mettre à jour votre système de gestion de contenu à l'aide des ID générés par YouTube dès qu'ils sont disponibles, au lieu d'utiliser une tâche de post-traitement par lot.

Ce document explique comment utiliser l'API Content ID de YouTube pour définir vos éléments dans le système de gestion des droits de YouTube. Il part du principe que vous définissez actuellement vos éléments à l'aide du flux DDEX YouTube et explique comment recréer les fonctionnalités du flux de contenu XML à l'aide de l'API. Plus précisément, elle utilise un exemple de flux de contenu XML et identifie les commandes API qui obtiennent le même résultat à l'aide de la bibliothèque cliente Python.

Méthodes pour fournir des données d'éléments à YouTube

L'utilisation du flux de contenu XML ou de l'API Content ID aboutit au même résultat: vous créez (ou mettez à jour) des ressources de gestion des droits YouTube dans votre compte partenaire. Dans certains cas, vous créez également (ou mettez à jour) des vidéos YouTube.

Le flux de contenu XML et l'API n'abordent pas la tâche de la même manière. Le flux de contenu XML vous permet de créer un fichier unique contenant toutes les informations sur les ressources et les relations entre elles. YouTube utilise le flux comme modèle pour créer les ressources réelles lors du processus d'importation groupée. L'API vous permet de créer des ressources une par une plutôt que par lot. Vous pouvez surveiller la progression et la réussite de chaque appel d'API et de ressource.

Lorsque vous créez des ressources directement à l'aide des méthodes de l'API, vous devez explicitement effectuer certaines actions que le processus de mise en ligne groupée de YouTube gère en arrière-plan. Vous devez notamment importer vos fichiers multimédias et résoudre les problèmes (en renouvelant certaines actions ou en signalant les erreurs). Vous devez également effectuer les actions dans le bon ordre : Par exemple, vous ne pouvez pas revendiquer une vidéo tant que vous ne l'avez pas créée.

Chacun des éléments de niveau racine dans le format de flux de contenu XML YouTube correspond à une ressource (ou propriété de ressource) que vous créez à l'aide des API YouTube.

Éléments XML et ressources d'API correspondantes
<asset> asset
<file> videos.fileDetails (depuis l'API YouTube Data) ou
thumbnail (depuis l'API YouTube Data) ou
reference
<ownership> ownership
<rights_admin> assetMatchPolicy (pour les règles de correspondance)
claims.policy (pour les règles d'utilisation)
<rights_policy> policy
<video> videos (de l'API YouTube Data)
<video_breaks> videoAdvertisingOption.adbreaks[ ]
<ad_policy> videoAdvertisingOption
<claim> claim
<playlist> playlist (de l'API YouTube Data)
<relationship> Multiples

Remarque:Pour le moment, l'API YouTube Content ID n'est pas compatible avec les fichiers de sous-titres, les bandes-annonces ni les fichiers de pochettes d'album.

Le traitement des éléments <relationship> illustre bien la différence entre le flux XML et l'API.

  • Un élément XML <relationship> indique qu'il existe une relation entre les éléments <item> et <related_item>, mais la nature de cette relation n'est pas explicite. Le processus de mise en ligne sur YouTube déduit la relation correcte à partir des types d'éléments. Par exemple, une relation entre un élément et une vidéo indique que YouTube doit utiliser le fichier vidéo comme référence pour l'élément, tandis qu'une relation entre une règle relative aux annonces et une vidéo définit la règle de la vidéo.

  • Avec l'API YouTube Content ID, vous utilisez des ressources d'API spécifiques qui définissent explicitement la relation appropriée. Pour utiliser une vidéo comme référence pour un élément, vous devez créer une ressource reference. Pour définir les règles relatives aux annonces pour une vidéo, vous devez créer une ressource videoAdvertisingOptions. L'élément doit exister pour que vous puissiez définir ses propriétés.

Importer des données d'éléments via un script

Pour importer des données d'éléments à l'aide des API, vous devez écrire un script capable d'envoyer des requêtes API, d'importer des fichiers et de créer des ressources de gestion des droits YouTube. Cette section fournit un tutoriel pour écrire le script.

Les principales étapes sont les suivantes:

  1. Créez un script de base qui utilise les API YouTube.
  2. Ajoutez du code permettant d'importer des fichiers multimédias.
  3. Ajoutez du code qui crée des ressources de gestion des droits.
  4. Opérationnalisez votre script pour qu'il fonctionne avec votre système de diffusion de contenu.

Un exemple de code est fourni à la fin du document (à l'exception de l'étape 4). Bien que le code soit écrit en Python, des bibliothèques clientes pour d'autres langages de programmation courants sont également disponibles.

Étape 1: Effectuer des appels d'API

Le tutoriel Envoyer une première demande explique comment écrire un script de base pour envoyer des requêtes YouTube Content API. L'exemple de script de ce tutoriel authentifie l'utilisateur, autorise l'utilisation des requêtes API et construit des ressources pour interagir avec l'API Content ID de YouTube.

Ce script sert de base au script utilisé dans cet exemple. Toutefois, comme indiqué ci-dessus, cet exemple explique comment créer et revendiquer des vidéos YouTube. Vous devez utiliser l'API YouTube Data pour mettre en ligne des vidéos YouTube. Pour que le script du tutoriel puisse également accéder à l'API YouTube Data, effectuez les deux ajouts suivants:

  • Autorisez l'accès à la fonctionnalité d'importation dans l'API YouTube Data en ajoutant son URI au paramètre scope dans l'appel flow_from_clientsecrets (comme indiqué à l'étape 2 du tutoriel).

    FLOW = flow_from_clientsecrets( 'client_secrets.json ',
           scope='https://www.googleapis.com/auth/youtubepartner https://www.googleapis.com/auth/youtube.upload',
           message= 'error message')

  • Créez une ressource permettant d'interagir avec l'API YouTube Data (à partir de l'étape 3 du tutoriel). 

    service = build("youtubePartner", "v1", http=http, static_discovery=False)
dataApi = build("youtube", "v3", http=http)

Étape 2: Importer des fichiers vidéo

L'étape suivante consiste à ajouter une fonction permettant d'importer des fichiers vidéo. Pour une fiabilité maximale, utilisez un protocole d'importation avec reprise. Ce protocole vous permet de reprendre une opération de téléchargement après une interruption du réseau ou un autre échec de transmission. Vous gagnez ainsi du temps et de la bande passante en cas de défaillance du réseau.

Le guide Mettre en ligne une vidéo, disponible dans la documentation de l'API YouTube Data, fournit un exemple de script d'importation : upload_video.py. Mettez à jour le script de base de l'étape 1 en ajoutant la fonction resumable_upload de upload_video.py. Vous devez également ajouter les instructions import et les définitions de variables dont dépend la fonction.

Étape 3: Créez des ressources YouTube pour la gestion des droits

Une fois la structure de base en place, vous êtes prêt à ajouter le code qui crée les éléments YouTube, les vidéos et les ressources associées.

L'ordre dans lequel vous créez les ressources est important. Par exemple, vous devez créer un élément et mettre en ligne une vidéo avant de pouvoir revendiquer la vidéo pour cet élément.

L'ordre général des opérations pour les éléments de films, de séries TV, de clips musicaux et de vidéos Web est le suivant:

  1. Créer la ressource d'élément (assets.insert)
  2. Modifier la propriété de l'élément (ownership.update) et la règle de correspondance (assetMatchPolicy.update)
  3. Créer la ressource vidéo (videos.insert), définir ses métadonnées et importer le fichier multimédia
  4. Mettre à jour les règles relatives aux annonces de la vidéo (videoAdvertisingOptions.update)
  5. Revendiquer la vidéo pour l'élément (claims.insert)
  6. Créer une référence pour l'élément à l'aide de la vidéo revendiquée (references.insert)

L'ordre des opérations est le même pour les enregistrements audio et les éléments de référence uniquement, en omettant les étapes 3 à 5:

  1. Créer la ressource d'élément (assets.insert)
  2. Modifier la propriété de l'élément (ownership.update) et la règle de correspondance (assetMatchPolicy.update)
  3. Créer une référence pour l'élément (references.insert) et importer le fichier multimédia

Le reste de cette section fournit des informations détaillées sur chacune de ces étapes, en comparant l'exemple de flux XML au code correspondant dans l'exemple de script.

Étape 3.1: Créer un élément

Le premier appel consiste à utiliser la méthode assets.insert de l'API. Elle correspond à la partie suivante du flux XML:

<asset type="web">
  <title>Broadcast Yourself!: Using the YouTube Live APIs to stream to the world</title>
  <description>See a preview of the Google I/O presentation.</description>
</asset>

Pour spécifier ces valeurs dans une ressource asset, vous devez définir les valeurs de propriété suivantes:

{
  "type": "web",
  "metadata": {
    "title": "Broadcast Yourself!: Using the YouTube Live APIs to stream to the world",
    "description": "See a preview of the Google I/O presentation."
  }
}

Extrayez la propriété id de la ressource renvoyée par l'API. Cette propriété identifie l'ID attribué par YouTube à l'élément de façon unique. Cette valeur est requise dans plusieurs appels d'API ultérieurs et est identifiée comme assetId plus loin dans cette documentation.

Étape 3.2: Modifiez la propriété de l'élément

Une fois que vous avez créé un élément, vous définissez sa propriété à l'aide de la méthode ownership.update de l'API. Cette étape correspond à la partie suivante du flux XML:

<ownership/>
<relationship>
  <item path="/feed/asset[1]"/>
  <related_item path="/feed/ownership[1]"/>
</relationship>

Le fichier XML utilise une balise <ownership> vide, ce qui indique que vous êtes le propriétaire du contenu dans le monde entier.

Votre requête API définira le paramètre de requête assetId sur l'assetId obtenu à l'étape 1. Elle spécifie également une ressource ownership avec les valeurs de propriété indiquées ci-dessous:

  • assetId (paramètre de requête): définissez l'assetId obtenu à l'étape 1.
  • general[0].ratio : 100
  • general[0].owner : "your_content_owner_name"
  • general[0].type : "exclude"
  • general[0].territories : []

{
  "general": [
    "ratio": 100,
    "owner": "your_content_owner_name",
    "type": "exclude",
    "territories": []
  ]
}

Ces propriétés indiquent que le propriétaire de contenu spécifié (vous devez remplacer your_content_owner_name par votre véritable nom de propriétaire de contenu) détient 100% (general[0].ratio) du contenu partout. En fait, cette ressource ownership indique que le propriétaire est propriétaire du contenu partout, sauf (general[0].type) dans la liste de territoires fournie (general[0].territories), mais comme la valeur de cette propriété est une liste vide, aucun territoire n'est réellement exclu.

Étape 3.3: Définir les règles de correspondance de l'élément

Le système de gestion des droits de YouTube propose deux méthodes pour associer une règle de correspondance à un élément ou une règle d'utilisation à une vidéo revendiquée:

  • Utilisez une règle précédemment enregistrée. Dans cette méthode, vous utilisez l'API pour récupérer vos règles enregistrées, trouver la règle que vous souhaitez utiliser, puis spécifier l'identifiant unique de cette règle lorsque vous définissez la règle de correspondance d'un élément ou que vous créez une revendication.

  • Définissez une ressource policy lors de la création de l'élément ou de la revendication. Dans ce cas, la ressource de règle n'est pas enregistrée et ne peut donc pas être appliquée à d'autres éléments ou revendications.

Nous vous recommandons d'utiliser la première méthode, qui repose sur les règles enregistrées. L'un des principaux avantages de cette approche est que si vous mettez à jour une règle enregistrée, celle-ci affecte automatiquement tous les éléments et revendications qui utilisent cette règle.

Toutefois, les exemples de code présentés dans ce document utilisent la seconde approche pour définir la règle de correspondance du nouvel élément, à l'aide de la méthode assetMatchPolicy.update de l'API. (Ce document utilise également la seconde méthode pour définir les règles d'utilisation, qui sont définies lorsque la vidéo est revendiquée.) Le document utilise la seconde approche, car les noms des règles enregistrées peuvent varier d'un partenaire à l'autre. cette approche garantit que le même code fonctionnera pour tout le monde.

Cette étape correspond à la partie suivante du flux XML:

<rights_policy>
  <name>Monetize developer videos</name>
</rights_policy>
<rights_admin owner="True" type="match"/>
<relationship>
  <item path="/feed/rights_admin[1]"/>
  <item path="/feed/rights_policy[1]"/>
  <related_item path="/feed/asset[1]"/>
</relationship>

Votre requête API définit le paramètre assetId sur la assetId obtenue à l'étape 1. Elle envoie également une ressource assetMatchPolicy qui définit les valeurs de propriété répertoriées ci-dessous:

{
  "rules": [
    {
      "action": "monetize",
      "conditions": {
        "requiredTerritories": {
          "type": "exclude",
          "territories": []
        }
      }
    }
  ]
}

L'exemple ci-dessous montre comment la ressource assetMatchPolicy serait construite si vous définissez une règle enregistrée comme règle de correspondance d'un élément. Dans votre code, vous devez remplacer la chaîne PolicyID par l'identifiant unique de la règle enregistrée.

{
  "policyId": "PolicyID"
}

Remarque:Le flux XML, comme la page Règles du Gestionnaire de contenu YouTube, spécifie les règles par nom. Pour récupérer l'ID d'une règle enregistrée, utilisez la méthode policies.list. Les ID de règle varient d'un partenaire à l'autre, même pour les règles par défaut.

Étape 3.4: Créez une ressource vidéo et importez le fichier multimédia

Vous pouvez importer votre vidéo à l'aide de la méthode videos.insert de l'API Data. Le guide Importations avec reprise identifie les appels HTTP à effectuer pour mettre en ligne des vidéos à l'aide d'un processus de mise en ligne avec reprise. Plusieurs bibliothèques clientes de nos API sont également compatibles avec les importations avec reprise. L'exemple de code ci-dessous utilise un processus d'importation avec reprise effectué à l'aide de la bibliothèque cliente Python des API Google.

Cette étape correspond à la partie suivante du flux XML:

<video>
  <title>Broadcast Yourself!: Using the YouTube Live APIs to stream to the world</title>
  <description>See a preview of the Google I/O presentation.</description>
  <genre>Entertainment</genre>
  <keyword>”Google I/O” “YouTube Live APIs”</keyword>
  <public>True</public>
</video>
<file type="video">
  <filename>GOOG_IO_Broadcast_Yourself.mov</filename>
</file>
<relationship>
  <item path="/feed/file[1]"/>
  <related_item path="/feed/video[1]"/>
</relationship>

Si vous écrivez du code personnalisé pour effectuer les appels d'API, vous envoyez une requête initiale qui crée la ressource video et renvoie une URL d'importation, puis vous envoyez une deuxième requête pour importer les données du fichier binaire vidéo vers cette URL. Si vous utilisez la bibliothèque cliente Python (comme dans l'exemple), vous envoyez la ressource video et les données du fichier binaire vidéo dans la même requête.

Pour créer la vidéo décrite dans l'exemple XML, votre requête API doit définir la valeur du paramètre part sur snippet,status, et la ressource video dans le corps de la requête doit définir les propriétés suivantes. La valeur snippet.categoryId (24) correspond à la catégorie Entertainment, qui correspond à la catégorie associée à la vidéo dans le flux XML. Pour en savoir plus sur les catégories de vidéos, consultez les annexes.

{
  "snippet": {
    "title": "Broadcast Yourself!: Using the YouTube Live APIs to stream to the world",
    "description": "See a preview of the Google I/O presentation.",
    "tags": ["Google I/O", "YouTube Live APIs"],
    "categoryId": 24
  },
  "status": {
    "privacyStatus": "private"
  }
}

Remarque:Nous vous recommandons de définir l'état de confidentialité d'une vidéo sur private lorsque vous la mettez en ligne, puis de le définir sur public plus tard au cours du processus. Si vous préférez importer la vidéo en tant que vidéo publique, définissez la propriété status.privacyStatus sur public.

Extrayez la propriété id de la ressource renvoyée par l'API. Cette propriété identifie l'ID vidéo attribué par YouTube comme identifiant unique de la vidéo. Cette valeur est requise dans plusieurs appels d'API ultérieurs et est identifiée comme videoId plus loin dans cette documentation.

Étape 3.5: Interrogez l'API Data pour déterminer quand la vidéo a été traitée

Certaines actions, comme la création d'une référence, nécessitent que YouTube ait terminé le traitement de votre vidéo. C'est pourquoi l'étape suivante du script consiste à s'assurer que la mise en ligne de la vidéo est terminée.

Pour vérifier l'état de l'importation, appelez la méthode videos.list de l'API Data et définissez les paramètres de requête suivants:

  • id: videoId (étape précédente)
  • part : "processingDetails"

L'API renvoie une liste de ressources video (contenant exactement une ressource). Vous devez vérifier la valeur de la propriété processingDetails.processingStatus de cette ressource pour déterminer si YouTube est toujours en train de traiter la vidéo. Une fois le traitement de la vidéo terminé, la valeur de la propriété n'est pas processing, comme succeeded ou failed.

L'exemple de code appelle la méthode videos.list toutes les 12 secondes pour déterminer si le traitement de la vidéo est terminé. Cette vérification de l'état ne correspond pas directement à un élément du fichier XML. il représente une action qu'une importation groupée gère implicitement lorsqu'elle traite le fichier XML.

Étape 3.6: Définir les règles relatives aux annonces

Une fois que YouTube a traité la vidéo, vous pouvez mettre à jour les paramètres d'annonces de la ressource video. Appelez la méthode videoAdvertisingOptions.update de l'API Content ID pour définir la règle relative aux annonces pour la vidéo. Cette action correspond à cette partie du flux XML:

<ad_policy>
  <instream standard="long" trueview="true">
    <prerolls>Allow</prerolls>
    <postrolls>Allow</postrolls>
    <midrolls>Deny</midrolls>
  </instream>
  <overlay>
    <adsense_for_video>Allow</adsense_for_video>
    <invideo>Allow</invideo>
  </overlay>
</ad_policy>
<relationship>
  <item path="/feed/ad_policy[1]"/>
  <related_item path="/feed/video[1]"/>
</relationship>

La règle présentée dans cet exemple permet à YouTube de diffuser TrueView annonces InStream ou annonces en superposition, y compris les annonces "longues". Annonces de 30 secondes, au début (pré-roll) ou à la fin (post-roll) de la vidéo.

Pour définir les règles relatives aux annonces, envoyez une demande qui définit le paramètre videoId sur la videoId obtenue précédemment. Le corps de la requête est une ressource videoAdvertisingOptions qui définit les propriétés affichées ci-dessous:

{
  "breakPosition": ["preroll", "postroll"],
  "adFormats": ["long", "trueview_instream", "overlay"]
}

Étape 3.7: Revendiquer la vidéo

Au cours de cette étape, vous revendiquez la vidéo que vous avez mise en ligne et définissez les règles d'utilisation de la vidéo en appelant la méthode claims.insert de l'API Content ID. Cette étape correspond à la partie suivante du flux XML:

<rights_policy>
  <rule action="monetize"/>
</rights_policy>
<rights_admin owner="True" type="match"/>
<claim type="audiovisual"
       asset="/feed/asset[1]"
       rights_admin="/feed/rights_admin[1]"
       rights_policy="/feed/rights_policy[1]"
       video="/feed/video[1]"/>

Comme pour les règles de correspondance d'éléments, l'exemple de script définit une règle ponctuelle au lieu d'associer une règle enregistrée à la vidéo. Toutefois, comme indiqué précédemment, nous vous encourageons à utiliser des règles enregistrées lorsque vous définissez des règles d'utilisation et de correspondance.

Dans la ressource claim que vous envoyez avec votre requête, définissez les propriétés affichées dans la ressource ci-dessous. Notez que les chaînes assetId et videoId doivent être remplacées par les valeurs obtenues par le script aux étapes précédentes.

{
  "assetId": assetId,
  "videoId": videoId,
  "contentType": "audiovisual",
  "policy": {
    "rules": [
      {
        "action": "monetize"
      }
    ]
  }
}

Extrayez la propriété id de la ressource renvoyée par l'API. Cette propriété indique l'ID attribué par YouTube à la revendication pour l'identifier de façon unique. Cette valeur est requise pour les appels d'API ultérieurs et est identifiée comme claimId plus loin dans cette documentation.

Étape 3.8: Créez une référence

Utilisez la méthode references.insert de l'API Content ID afin de créer une référence pour le système Content ID. Vous pouvez créer une référence en utilisant une vidéo revendiquée comme contenu de référence ou en important un fichier de référence dans le cadre de l'appel d'API. Si vous créez une référence à partir d'une vidéo revendiquée, comme le fait l'exemple de script, la revendication doit déjà exister.

Dans votre requête API, définissez le paramètre de requête claimId sur la claimid obtenue à l'étape précédente. Envoyez également une ressource reference qui définit les propriétés affichées ci-dessous:

{
  "contentType": "audiovisual"
}

Pour créer un élément de référence uniquement (sans vidéo revendiquée), apportez les modifications suivantes à la demande ci-dessus:

  1. Omettez le paramètre de requête claimId.
  2. Ajoutez la propriété assetId à la ressource reference importée.
  3. Importez le fichier de référence en tant que media_body de la requête API.

Étape 3.9: Rendez la vidéo publique

Si vous avez suivi les bonnes pratiques et défini l'état de confidentialité de votre vidéo sur private lors de sa création, vous pouvez le définir sur public une fois la mise en ligne terminée. Utilisez les méthodes videos.list et videos.update de l'API YouTube Data pour récupérer et mettre à jour la ressource video de la vidéo que vous venez de mettre en ligne.

Commencez par appeler la méthode videos.list de l'API Data avec les paramètres de requête suivants:

  • part=status
  • id=videoId

Cette méthode renvoie une liste contenant une ressource, qui décrit la vidéo avec le videoId spécifié. Définissez la valeur de la propriété status.privacyStatus de cette ressource sur public, puis appelez la méthode videos.update de l'API Data. Définissez le paramètre de requête suivant:

  • part=status

Le corps de la requête est la ressource vidéo modifiée.

Étape 4: Intégrez votre site à votre système de diffusion de contenu

L'exemple de code fourni en annexe inclut les métadonnées spécifiques aux ressources directement dans le script. Dans la pratique, vous souhaiterez probablement intégrer le script à votre système de gestion de contenu. Pour un système de diffusion de contenu plus complet, vous pouvez ajouter les étapes suivantes:

  • Interrogez votre système de gestion de contenu pour identifier les éléments à ajouter ou à mettre à jour.
  • Récupérez les métadonnées des éléments à partir du système de gestion de contenu.
  • Mettez à jour le système de gestion de contenu avec les ID fournis par YouTube pour les éléments, les vidéos, les références et les revendications créés, ainsi que les codes temporels permettant d'enregistrer la date de la dernière mise à jour des éléments.

Annexe

Exemple de fichier de flux XML

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.youtube.com/schemas/cms/2.0"
      notification_email="[email protected]"
      channel="your_channel" content_owner="your_name">
 <asset type="web">
   <title>Broadcast Yourself!: Using the YouTube Live APIs to stream to the world</title>
   <description>See a preview of the Google I/O presentation.</description>
 </asset>
 <video>
   <title>Broadcast Yourself!: Using the YouTube Live APIs to stream to the world</title>
   <description>See a preview of the Google I/O presentation.</description>
   <genre>Entertainment</genre>
   <keyword>”Google I/O” “YouTube Live APIs”</keyword>
   <public>True</public>
 </video>
 <file type="video">
   <filename>GOOG_IO_Broadcast_Yourself.mov</filename>
 </file>
  <relationship>
   <item path="/feed/file[1]"/>
   <related_item path="/feed/video[1]"/>
 </relationship>
 <content_rating system="youtube">L0 N0 S0 V0 D0 F0</content_rating>
 <relationship>
   <item path="/feed/content_rating[1]"/>
   <related_item path="/feed/video[1]"/>
 </relationship>
 <ownership/>
 <relationship>
   <item path="/feed/asset[1]"/>
   <related_item path="/feed/ownership[1]"/>
 </relationship>
 <rights_policy>
   <name>Monetize developer videos</name>
 </rights_policy>
 <rights_admin owner="True" type="match"/>
 <relationship>
   <item path="/feed/rights_admin[1]"/>
   <item path="/feed/rights_policy[1]"/>
   <related_item path="/feed/asset[1]"/>
 </relationship>
 <ad_policy>
   <instream standard="long" trueview="true">
     <prerolls>Allow</prerolls>
     <postrolls>Allow</postrolls>
     <midrolls>Deny</midrolls>
   </instream>
   <overlay>
     <adsense_for_video>Allow</adsense_for_video>
     <invideo>Allow</invideo>
   </overlay>
 </ad_policy>
 <relationship>
   <item path="/feed/ad_policy[1]"/>
   <related_item path="/feed/video[1]"/>
 </relationship>
 <claim type="audiovisual" asset="/feed/asset[1]" rights_admin="/feed/rights_admin[1]" rights_policy="/feed/rights_policy[1]" video="/feed/video[1]"/>
</feed>

Exemple de script

L'exemple de code utilise la bibliothèque cliente Python des API Google.

#!/usr/bin/python2.6
# -*- coding: utf-8 -*-
#
# Copyright (C) 2012 Google Inc.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#      http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

"""Simple command-line sample for YouTube Content ID API.

Command-line application that retrieves the information
about given content owner.

Usage:
  $ python yt_partner_api.py --file="/path/to/reference/file"

You can also get help on all the command-line flags the program understands
by running:

  $ python yt_partner_api.py --help

To get detailed log output run:

  $ python yt_partner_api.py --logging_level=DEBUG \
    --file="/path/to/reference/file"
"""

import gflags
import httplib
import httplib2
import json
import logging
import sys
import time
import os

from apiclient.discovery import build
from apiclient.errors import HttpError
from apiclient.http import MediaFileUpload
from oauth2client.file import Storage
from oauth2client.client import AccessTokenRefreshError
from oauth2client.client import flow_from_clientsecrets
from oauth2client.tools import run

# Explicitly tell the underlying HTTP transport library not to retry, since
# we are handling retry logic ourselves.
httplib2.RETRIES = 1

# Maximum number of times to retry before giving up.
MAX_RETRIES = 10

# Always retry when these exceptions are raised.
RETRIABLE_EXCEPTIONS = (httplib2.HttpLib2Error, IOError, httplib.NotConnected,
  httplib.IncompleteRead, httplib.ImproperConnectionState,
  httplib.CannotSendRequest, httplib.CannotSendHeader,
  httplib.ResponseNotReady, httplib.BadStatusLine)

# Always retry when an apiclient.errors.HttpError with one of these status
# codes is raised.
RETRIABLE_STATUS_CODES = [500, 502, 503, 504]

#httplib2.debuglevel = 4
FLAGS = gflags.FLAGS

# The CLIENT_SECRETS_FILE variable specifies the name of a file that contains
# the OAuth 2.0 information for this application, including its client_id and
# client_secret. You can acquire an OAuth 2.0 client ID and client secret from
# the Google API Console at
# https://console.cloud.google.com/.
# See the "Registering your application" instructions for an explanation
# of how to find these values:
# https://developers.google.com/youtube/partner/guides/registering_an_application
# For more information about using OAuth2 to access Google APIs, please visit:
#   https://developers.google.com/accounts/docs/OAuth2
# For more information about the client_secrets.json file format, please visit:
#   https://developers.google.com/api-client-library/python/guide/aaa_client_secrets
CLIENT_SECRETS = 'client_secrets.json'

# Helpful message to display if the CLIENT_SECRETS file is missing.
MISSING_CLIENT_SECRETS_MESSAGE = """
WARNING: Please configure OAuth 2.0

To make this sample run you will need to populate the client_secrets.json file
found at:

%s

with information from the API Console
<https://console.cloud.google.com/ >

""" % os.path.join(os.path.dirname(__file__), CLIENT_SECRETS)

# Flags definition
#
# The gflags module makes defining command-line options easy for
# applications. Run this program with the '--help' argument to see
# all the flags that it understands.
gflags.DEFINE_enum('logging_level', 'ERROR',
    ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'],
    'Set the level of logging detail.')

gflags.DEFINE_string('file', None, 'The video file to upload.')

def resumable_upload(insert_request):
  response = None
  error = None
  retry = 0
  while response is None:
    try:
      print "Uploading file..."
      status, response = insert_request.next_chunk()
      if 'id' in response:
        print "'video id: %s was successfully uploaded." % (response['id'])
        return response['id']
      else:
        exit("The upload failed with an unexpected response: %s" % response)
    except HttpError, e:
      if e.resp.status in RETRIABLE_STATUS_CODES:
        error = "A retriable HTTP error %d occurred:\n%s" % (e.resp.status,
                                                             e.content)
      else:
        raise
    except RETRIABLE_EXCEPTIONS, e:
      error = "A retriable error occurred: %s" % e

    if error is not None:
      print error
      retry += 1
      if retry > MAX_RETRIES:
        exit("No longer attempting to retry.")

      max_sleep = 2 ** retry
      sleep_seconds = random.random() * max_sleep
      print "Sleeping %f seconds and then retrying..." % sleep_seconds
      time.sleep(sleep_seconds)
  return None

def createRequest(service, resource, operation, **kwargs):
  request = getattr(service, resource)()
  request = getattr(request, operation)(**kwargs)
  return request

def executeOperation(service, resource, operation, **kwargs):
  request = getattr(service, resource)()
  request = getattr(request, operation)(**kwargs)
  return_value = request.execute()
  print json.dumps(return_value)
  return return_value

def main(argv):
  # Let the gflags module process the command-line arguments
  try:
    argv = FLAGS(argv)
  except gflags.FlagsError, e:
    print '%s\nUsage: %s ARGS\n%s' % (e, argv[0], FLAGS)
    sys.exit(1)

  # Set up a Flow object to be used if we need to authenticate.
  FLOW = flow_from_clientsecrets(CLIENT_SECRETS,
             scope='https://www.googleapis.com/auth/youtubepartner https://www.googleapis.com/auth/youtube.upload',
             message=MISSING_CLIENT_SECRETS_MESSAGE)

  # Set the logging according to the command-line flag
  logging.getLogger().setLevel(getattr(logging, FLAGS.logging_level))

  # If the Credentials don't exist or are invalid run through the native client
  # flow. The Storage object will ensure that if successful the good
  # Credentials will get written back to a file.
  storage = Storage('yt_partner_api.dat')
  credentials = storage.get()
  if credentials is None or credentials.invalid:
    credentials = run(FLOW, storage)

  # Create an httplib2.Http object to handle our HTTP requests and authorize it
  # with our good Credentials.
  http = httplib2.Http()
  http = credentials.authorize(http)

  # Create service and retrieve content owner service.
  partnerApi = build("youtubePartner", "v1", http=http)
  dataApi = build("youtube", "v3", http=http)

  try:
    title = 'Top Ten Ridiculous test #u',
    monetize_policy = {'rules': [{'action': 'monetize'}]}

    # Create the asset
    kwargs = {}
    metadata = {'title': title,
                'description': 'Wow this is a really long description'}
    kwargs['body'] = {'metadata': metadata, 'type': 'web'}
    insert_asset = executeOperation(partnerApi, 'assets', 'insert', **kwargs)
    asset_id = insert_asset['id']
    print 'Asset ID is ' + asset_id

    # Set asset ownership
    kwargs = {'assetId': asset_id}
    ownership = {'ratio': 100,
                 'owner': 'psomusictest',
                 'type': 'exclude',
                 'territories': []}
    body = {'general': [ownership], 'id': asset_id}
    kwargs['body'] = body
    set_ownership = executeOperation(partnerApi, 'ownership', 'update',
                                     **kwargs)

    # Set match policy
    kwargs = {'assetId': asset_id, 'body': monetize_policy}
    set_match_policy = executeOperation(partnerApi, 'assetMatchPolicy',
                                        'update', **kwargs)

    # Insert video using resumable upload
    snippet = {'title': title,
               'description': 'Wow this is a really long description',
               'tags': ['fizzle', 'sizzle', 'razzle dazzle'],
               'categoryId': '24'}
    status = {'privacyStatus': 'private'}
    body = { 'snippet': snippet, 'status': status }
    kwargs = {'part': 'snippet,status',
              'body': body,
              'media_body': MediaFileUpload(FLAGS.file,
                                            chunksize=-1,
                                            resumable=True)}

    insert_video = createRequest(dataApi, 'videos', 'insert', **kwargs)
    video_id = resumable_upload(insert_video)

    if not video_id:
      print 'video upload failed, so the rest of this exercise is pointless'
      return
   # Poll to see when video is processed
    kwargs = {'id': video_id, 'part': 'processingDetails'}
    check_video_status = createRequest(dataApi, 'videos', 'list', **kwargs)
    video_processed = False
    sleep_seconds = 12
    while not video_processed:
      status = check_video_status.execute()
      processingDetails = status['items'][0]['processingDetails']
      if processingDetails['processingStatus'] != 'processing':
        print 'hooray, it ' + processingDetails['processingStatus']
        video_processed = True
      elif not 'processingProgress' in processingDetails:
        time.sleep(sleep_seconds)
      else:
        print ('so far, we processed %d/%d parts' % (
            processingDetails['processingProgress']['partsProcessed'],
            processingDetails['processingProgress']['partsTotal']))
        time.sleep(sleep_seconds)

    # Claim the video
    body = {'assetId': asset_id,
            'videoId': video_id,
            'policy': monetize_policy,
            'contentType': 'audiovisual'}
    kwargs = {'body': body}
    claim_video = executeOperation(partnerApi, 'claims', 'insert', **kwargs)
    claim_id = claim_video['id']
    print 'claim ID is ' + claim_id

    # Create the reference
    body = {'assetId': asset_id,
            'videoId': video_id,
            'contentType': 'audiovisual'}
    kwargs = {'claimId': claim_id, 'body': body}
    create_reference = executeOperation(partnerApi, 'references', 'insert',
                                        **kwargs)

    # Set ad policy (update video advertising options)
    ads = {'breakPosition': ['preroll','postroll'],
           'adFormats': ['standard_instream','trueview_instream','overlay']}
    kwargs = {'videoId': video_id, 'body': ads}
    ads = executeOperation(partnerApi, 'videoAdvertisingOptions',
                           'update', **kwargs)

    #9 Update video's privacy status to public
    kwargs = {'part': 'status', 'id': video_id}
    video = executeOperation(dataApi, 'videos', 'list', **kwargs)
    video['items'][0]['status']['privacyStatus'] = 'public'
    kwargs = {'part': 'status', 'body': video['items'][0]}
    video = executeOperation(dataApi, 'videos', 'update', **kwargs)

  except AccessTokenRefreshError:
    print ("The credentials have been revoked or expired, please re-run"
      " the application to re-authorize")

if __name__ == '__main__':
  main(sys.argv)

Autres actions de l'API

Récupérer une liste de catégories de vidéos à l'aide de l'API Data

L'exemple de code définit la valeur de la propriété snippet.categoryID sur 24, ce qui correspond à la valeur "Entertainment" genre musical. Si vous souhaitez que votre script recherche l'ID d'un genre donné (plutôt que de coder en dur les ID de catégorie), appelez la méthode videoCategories.list de l'API Data et définissez les paramètres de requête suivants:

  • part=snippet
  • regionCode=US (vous pouvez définir une valeur différente pour regionCode afin d'extraire les catégories de vidéos d'un autre pays)

Pour chaque ressource videoCategory de la réponse de l'API, vous devez vérifier la valeur de la propriété snippet.title pour identifier un nom de catégorie, puis extraire la propriété id de la catégorie souhaitée. Voici à quoi ressemble la ressource videoCategory pour la catégorie "Divertissement" catégorie:

{
  "id": "24",
  "kind": "youtube#videoCategory",
  "etag": "\"idnvT0N6oxG_2o6LCWUdZsqtqtk/I5rstjIK5PCItZFyWV-uw\"",
  "snippet": {
    "channelId": "UCBR8-60-B28hp2BmDPdntcQ",
    "title": "Entertainment"
  }
}