Gérer les éléments de composition

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 YouTube. Si l'API YouTube Content ID n'apparaît pas dans la console Google APIs, consultez le Centre d'aide YouTube pour en savoir plus sur le Programme Partenaire YouTube.

Remarque:Les informations de ce guide s'appliquent spécifiquement aux éléments de type composition.

Dans le système de gestion des droits de YouTube, un asset désigne un contenu protégé par des droits de propriété intellectuelle. YouTube reconnaît différents types d'éléments, comme les films, les clips musicaux, les enregistrements audio et les compositions.

Cependant, en raison de la nature complexe de la propriété et des droits des compositions, YouTube utilise un modèle d'éléments à deux niveaux pour les éléments de type composition. Le modèle est conçu pour tenir compte des éléments suivants:

  • Chaque enregistrement audio est associé à une composition.
  • Les propriétaires de contenu doivent souvent appliquer la propriété des droits de publication d'un même titre ou d'une même composition à différents enregistrements audio.

Ce document présente le modèle d'élément de type composition de YouTube. Elle explique également comment les deux types d'éléments de type composition sont utilisés dans les méthodes de l'API YouTube Content ID.

Comprendre le modèle d'élément de composition

Le modèle d'élément de YouTube définit deux représentations différentes des éléments de type composition:

  • Une part de composition représente les informations qu'un éditeur spécifique fournit sur un élément de composition. Ainsi, une part de la composition n'identifie que les métadonnées, les données de propriété et les règles que cet éditeur unique fournit pour la composition.

    Une part de la composition peut être associée à de nombreux enregistrements audio.

  • Une vue "Composition" représente l'élément de composition intégré à un enregistrement audio. Chaque enregistrement audio correspond à une seule vue de la composition, laquelle représente l'ensemble canonique d'informations affiché par YouTube à propos d'une composition. Les métadonnées, les données de propriété et les règles de la vue Composition sont déterminées à partir des données de tous les éléments Part de la composition associés.

    Une vue Composition peut être mappée à zéro, une ou plusieurs parts de la composition. Toutefois, une vue Composition n'est mappée à plusieurs parts de la composition que lorsqu'une composition est associée à plusieurs propriétaires.

    Sachez qu'un même propriétaire de contenu peut utiliser l'API pour représenter plusieurs propriétaires d'une composition. Par conséquent, il peut posséder plusieurs parts de cette composition. Par exemple, un agrégateur de droits numériques peut obtenir les droits d'une même composition auprès de différentes parties dans différents territoires. L'agrégateur serait constitué d'entités distinctes représentant ces droits, correspondant à différentes parts de la composition dans le modèle YouTube. Les différentes parts de la composition peuvent toujours être associées aux mêmes vues de la composition.

Le schéma suivant illustre ce modèle. Dans le diagramme :

  • Les cercles sont des enregistrements audio.
  • Les carrés sont des vues de composition.
  • Les triangles sont des parts de la composition. Chaque triangle de couleur représente un propriétaire de contenu différent. Les petits triangles à l'intérieur des carrés indiquent les données qui sont fusionnées pour générer l'ensemble canonique d'informations affiché par YouTube à propos d'une composition. YouTube utilise ces données pour calculer la propriété et les règles d'une composition.

Diagramme illustrant les relations entre les enregistrements audio, les vues de la composition et les parts de la composition

Deux types d'ID d'éléments

YouTube attribue un ID aux parts de la composition et aux vues de la composition, qui sont toutes deux considérées comme des ID d'éléments. Toutefois, ils ne sont pas interchangeables dans l'API. Dans cette optique, le reste de ce document utilise les termes shareId et viewId pour désigner les ID attribués respectivement aux parts de la composition et aux vues de la composition.

En général, lorsque vous récupérez ou mettez à jour les informations que vous fournissez à propos d'un élément, vous utilisez un shareId. Si vous récupérez l'ensemble canonique d'informations que YouTube affiche à propos d'un élément, vous utiliserez un viewId.

Si vous revenez au schéma de la section précédente, vous constaterez que les enregistrements audio et les vues de composition sont indiqués par des chiffres (SR1, CV1, etc.). Les chiffres reflètent la relation 1:1 entre les enregistrements audio et les vues de la composition. Par conséquent, si vous souhaitez récupérer l'ensemble canonique d'informations sur la composition d'un enregistrement audio spécifique, vous devez utiliser l'élément viewId de cette composition.

En revanche, les parts de la composition sont indiquées par des lettres (CSb, etc.). Les lettres représentent différents propriétaires de contenu. Par conséquent, si vous êtes le propriétaire du contenu vert et que vous souhaitez récupérer les métadonnées ou les données de propriété que vous avez fournies pour un élément de type composition, vous devez utiliser shareId pour récupérer ces informations.

Utiliser des ID d'éléments dans les méthodes d'API

Le reste de ce document explique comment les différentes méthodes d'API gèrent shareIds et viewIds lorsque ces ID sont utilisés comme valeurs de paramètre ou de propriété. Les méthodes d'API étant classées par ordre alphabétique, il peut être utile de commencer par suivre les étapes typiques associées à la création d'un élément de composition et à son association à un enregistrement audio.

  1. Appelez la méthode assets.insert pour créer un élément de composition. La réponse de l'API est une ressource asset dans laquelle la propriété id est une shareId.

  2. Appelez la méthode ownership.update pour définir les données de propriété pour la part de la composition. Définissez le paramètre assetId de la méthode sur la valeur shareId obtenue à l'étape 1.

  3. Appelez la méthode assetMatchPolicy.update pour définir les données de règle pour la part de la composition. La règle s'applique aux vidéos revendiquées qui contiennent la composition. Définissez le paramètre assetId de la méthode sur la valeur shareId obtenue à l'étape 1.

  4. Appelez la méthode assetRelationships.insert pour identifier les enregistrements audio qui contiennent la composition. Dans la ressource assetRelationship que vous insérez, définissez la propriété parentAssetId sur l'ID d'élément de l'enregistrement audio. Définissez la propriété childAssetId sur la valeur shareId obtenue à l'étape 1.

  5. Si vous stockez un mappage de viewIds avec shareIds, vous pouvez récupérer viewId en appelant la méthode assetRelationships.list et en définissant le paramètre assetId sur l'ID d'élément de l'enregistrement audio. Une relation dans l'ensemble de résultats identifiera l'ID d'élément de l'enregistrement audio comme étant parentAssetId. Dans cette relation, le childAssetId identifie la viewId mappée au shareId obtenu à l'étape 1.

Une fois l'élément créé, vous pouvez utiliser l'une des méthodes décrites dans ce document pour récupérer des informations à son sujet, le mettre à jour ou le supprimer.

assets.get/assets.list

Les méthodes assets.get et assets.list récupèrent des informations sur un élément ou une liste d'éléments. Les deux méthodes acceptent le même ensemble de paramètres de requête.

Trois de ces paramètres (fetchMatchPolicy, fetchMetadata et fetchOwnership) utilisent les valeurs effective et mine pour indiquer si vous voulez récupérer l'ensemble de données canonique sur l'élément ou si vous voulez récupérer les données que vous avez fournies sur celui-ci. Ces valeurs sont un vestige de l'ancien modèle d'éléments de composition de YouTube, qui traitait une vue de composition et ses parts de la composition comme une seule entité.

Toutefois, les valeurs sont toujours prises en charge dans le modèle à deux niveaux. Le contenu de la réponse de l'API dépend à la fois de la valeur du paramètre et de la façon dont les requêtes fournissent shareIds ou viewIds. Notez que la méthode assets.get utilise le paramètre assetId pour spécifier l'ID de l'élément, tandis que la méthode assets.list utilise le paramètre id.

La liste ci-dessous explique comment les valeurs des paramètres de requête affectent le contenu des réponses de l'API pour ces deux méthodes.

  • fetchMatchPolicy
    • Si l'ID de l'élément (paramètre id ou assetId) spécifie une propriété shareId :
      • Si le paramètre fetchMatchPolicy est défini sur mine, la réponse de l'API contient la règle définie par le propriétaire de contenu qui autorise la requête API définie pour la part de la composition.
      • Si le paramètre fetchMatchPolicy est défini sur effective, l'API renvoie une erreur 400.
    • Si l'ID de l'élément spécifie une viewId :
      • Si le paramètre fetchMatchPolicy est défini sur mine et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à l'ID de vue, l'API renvoie la règle de correspondance définie pour cette part de la composition.
      • Si le paramètre fetchMatchPolicy est défini sur mine et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à l'ID de vue, l'API renvoie une erreur 400.
      • Si le paramètre fetchMatchPolicy est défini sur effective, l'API renvoie la règle de correspondance canonique pour la vue de composition. Ces règles de correspondance prennent en compte les règles de correspondance de tous les partages de la composition associés à viewId, quels que soient les propriétaires de contenu qui détiennent ces partages.
  • fetchMetadata
    • Si l'ID de l'élément spécifie une shareId :
      • Si le paramètre fetchMetadata est défini sur mine, la réponse de l'API contient les métadonnées de l'élément que le propriétaire de contenu autorise la requête API définie pour la part de la composition.
      • Si le paramètre fetchMetadata est défini sur effective, l'API renvoie une erreur 400.
    • Si l'ID de l'élément spécifie une viewId :
      • Si le paramètre fetchMetadata est défini sur mine et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à l'ID de vue, l'API renvoie les métadonnées définies pour cette part de la composition.
      • Si le paramètre fetchMetadata est défini sur mine et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à l'ID de vue, l'API renvoie une erreur 400.
      • Si le paramètre fetchMetadata est défini sur effective, l'API renvoie l'ensemble canonique de métadonnées pour la vue de composition. Ces métadonnées prennent en compte les métadonnées d'élément fournies pour toutes les parts de la composition associées à viewId, quels que soient les propriétaires de contenu qui détiennent ces parts.
  • fetchOwnership
    • Si l'ID de l'élément spécifie une shareId :
      • Si le paramètre fetchOwnership est défini sur mine, la réponse de l'API contient les données de propriété que le propriétaire de contenu autorise la requête API définie pour la part de la composition.
      • Si le paramètre fetchOwnership est défini sur effective, l'API renvoie une erreur 400.
    • Si l'ID de l'élément spécifie une viewId :
      • Si le paramètre fetchOwnership est défini sur mine et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à l'ID de vue, l'API renvoie les données de propriété définies pour cette part de la composition.
      • Si le paramètre fetchOwnership est défini sur mine et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à l'ID de vue, l'API renvoie une erreur 400.
      • Si le paramètre fetchOwnership est défini sur effective, l'API renvoie les données de propriété canoniques pour la vue de composition. Ces données prennent en compte les données de propriété de toutes les parts de la composition associées à viewId, quels que soient les propriétaires de contenu qui détiennent ces parts.
  • fetchOwnershipConflicts
    • Si l'ID de l'élément spécifie shareId, l'API renvoie une erreur 400.
    • Si l'ID de l'élément spécifie une viewId, l'API renvoie la liste des conflits de propriété associés à la vue "Composition".

assets.insert

Cette méthode crée une ressource asset, et YouTube attribue un ID pour l'identifier de manière unique. Cet ID, qui est renvoyé en tant que valeur de la propriété id dans la réponse de l'API, est de type shareId.

Remarque:Pour rappel, shareIds et viewIds ne sont utilisés que pour les assets de composition. Les autres types d'éléments n'utilisent pas de modèle à deux niveaux pour gérer leurs données.

assets.update et assets.patch

Ces méthodes permettent de mettre à jour les métadonnées d'un élément. Dans les deux demandes, le paramètre assetId identifie l'asset en cours de mise à jour. De plus, dans les deux requêtes, le corps de la requête est une ressource asset dans laquelle la valeur de la propriété id doit correspondre à celle du paramètre assetId.

  • Si le paramètre assetId et la propriété id spécifient shareId, la requête API met à jour la part de la composition spécifiée.
  • Si le paramètre assetId et la propriété id spécifient un viewId, et que le propriétaire de contenu qui autorise la requête ne possède qu'une seule part de la composition associée à ce viewId, la requête API met à jour cette part de la composition.
  • Si le paramètre assetId et la propriété id spécifient un viewId, et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à ce viewId, la requête API renvoie une erreur 400.

assetMatchPolicy.get

Cette méthode renvoie la règle de correspondance définie pour un élément spécifié. Le paramètre assetId de la requête identifie le composant.

  • Si le paramètre assetId spécifie un élément shareId, la réponse de l'API contient les métadonnées de l'élément dont le propriétaire de contenu autorise la requête API définie pour la part de la composition.
  • Si le paramètre assetId spécifie un élément viewId, l'API renvoie l'ensemble canonique de métadonnées pour la vue de composition. Ces métadonnées prennent en compte les métadonnées d'élément fournies pour toutes les parts de la composition associées à viewId, quels que soient les propriétaires de contenu qui détiennent ces parts.

assetMatchPolicy.update et assetMatchPolicy.patch

Ces méthodes modifient la règle de correspondance de l'élément spécifié. Le paramètre assetId de la requête identifie le composant.

  • Si le paramètre assetId spécifie une shareId, la requête API met à jour la règle de correspondance pour cette part de la composition.
  • Si le paramètre assetId spécifie une viewId et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à cette viewId, la requête API met à jour la règle de correspondance pour cette part de la composition.
  • Si le paramètre assetId spécifie une viewId et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à cette viewId, la requête API renvoie une erreur 400.

assetRelationships.list

Cette méthode renvoie une liste de relations entre les éléments d'un élément donné. Le paramètre assetId de la requête identifie le composant.

  • Si le paramètre assetId spécifie shareId, la réponse de l'API contient une liste d'assets Enregistrement audio associés. La liste peut contenir plusieurs éléments. Dans chaque ressource assetRelationship, l'ID d'élément de l'enregistrement audio correspond à parentAssetId, et l'ID à shareId à childAssetId.
  • Si le paramètre assetId spécifie une viewId, la réponse de l'API identifie l'enregistrement audio associé à cette viewId. La réponse contient une ressource au maximum.
  • Si le paramètre assetId identifie un asset Enregistrement audio, la réponse de l'API peut contenir plusieurs relations.
    • Si l'ID d'élément de l'enregistrement audio est le parentAssetId dans une ressource assetRelationship renvoyée, childAssetId identifie la vue de la composition (viewId) associée à cet enregistrement audio. Chaque enregistrement audio est associé à une relation de ce type.
    • Si l'ID d'élément de l'enregistrement audio est childAssetId, parentAssetId identifie une vidéo contenant l'enregistrement audio, par exemple un clip musical ou une vidéo de piste artistique. Chaque enregistrement audio peut avoir plusieurs relations de ce type.

assetRelationships.insert

Cette méthode permet d'établir une relation entre deux assets. Vous devez appeler cette méthode pour indiquer que vous détenez une part de la composition associée à un enregistrement audio.

Dans la ressource assetRelationship du corps de la requête, définissez la propriété parentAssetId sur l'ID d'élément de l'enregistrement audio. Définissez la propriété childAssetId sur shareId.

assetSearch.list

Cette méthode recherche des éléments en fonction de leurs métadonnées. La réponse de l'API contient une liste de ressources assetSearch, dans laquelle la propriété id de chaque ressource identifie un ID d'élément. En réalité, la valeur de la propriété id est un ID d'élément.

  • Si la ressource assetSearch identifie une composition, la valeur de la propriété id sera shareId.

assetShares.list

Cette méthode renvoie un mappage des vues de la composition avec les parts de la composition. Le paramètre assetId de la requête peut spécifier une viewId ou une shareId.

  • Si le paramètre assetId spécifie une viewId, la réponse de l'API contient une liste de ressources assetShare. Chaque ressource identifie une part de la composition associée à la vue de composition spécifiée et appartenant au propriétaire de contenu qui autorise la demande.

    La réponse de l'API peut contenir plusieurs ressources assetShare. Le cas d'utilisation courant dans lequel un viewId est mappé à plusieurs shareIds appartenant au même propriétaire de contenu est décrit dans la section Comprendre le modèle d'asset de type Composition de ce document.

  • Si le paramètre assetId spécifie une shareId, la réponse de l'API contient une liste de ressources assetShare. Chaque ressource identifie une vue de composition associée à la part de la composition spécifiée. La réponse contiendra une ressource pour chaque enregistrement audio auquel la part de la composition est associée. (Chaque enregistrement audio est associé à une seule vue de la composition.)

claimSearch.list

Cette méthode renvoie une liste de revendications correspondant aux critères de recherche spécifiés. Le paramètre assetId de la méthode vous permet de rechercher les revendications associées à un élément particulier.

  • Si la requête API spécifie un shareId, l'API renvoie un code de réponse 400.

  • Si la requête API spécifie un élément viewId, l'API renvoie une liste de revendications associées à la vue de composition spécifiée, qui correspond à un seul élément Enregistrement audio.

metadataHistory.list

Cette méthode renvoie la liste de toutes les métadonnées fournies pour un élément, quel que soit le propriétaire de contenu qui les a fournies. Le paramètre assetId de la requête identifie le composant pour lequel les données sont récupérées.

  • Si la requête API spécifie un shareId, l'API renvoie l'ensemble de métadonnées le plus récent pour cette part de la composition.

  • Si la requête API spécifie un élément viewId, l'API renvoie une liste dans laquelle chaque entrée contient le dernier ensemble de métadonnées fourni pour toute part de la composition associée à cette vue de composition.

ownership.get

Cette méthode renvoie les données de propriété définies pour un élément donné. Le paramètre assetId de la requête identifie le composant.

  • Si le paramètre assetId spécifie un élément shareId, la réponse de l'API contient les données de propriété que le propriétaire de contenu autorise la requête API définie pour le partage de la composition.
  • Si le paramètre assetId spécifie un élément viewId, l'API renvoie l'ensemble canonique de données de propriété pour la vue de composition. La réponse synthétise les données de propriété fournies pour tous les partages de la composition associés à viewId, quels que soient les propriétaires de contenu qui en sont propriétaires.

owner.update et owner.patch

Ces méthodes permettent de modifier les données de propriété d'un élément donné. Le paramètre assetId de la requête identifie le composant.

  • Si le paramètre assetId spécifie une shareId, la requête API met à jour les données de propriété pour cette part de la composition.
  • Si le paramètre assetId spécifie une viewId et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à cette viewId, la requête API met à jour les données de propriété pour cette part de la composition.
  • Si le paramètre assetId spécifie une viewId et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à cette viewId, la requête API renvoie une erreur 400.

ownershipHistory.list

Cette méthode renvoie la liste de toutes les données de propriété fournies pour un élément, quel que soit le propriétaire de contenu qui les a fournies. Le paramètre assetId de la requête identifie le composant pour lequel les données sont récupérées.

  • Si la requête API spécifie un shareId, l'API renvoie l'ensemble de données de propriété le plus récent pour cette part de la composition.

  • Si la requête API spécifie un viewId, l'API renvoie une liste dans laquelle chaque entrée contient le dernier ensemble de données de propriété fourni pour toute part de la composition associée à cette vue de la composition.