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.
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.
-
Appelez la méthode
assets.insert
pour créer un élément de composition. La réponse de l'API est une ressourceasset
dans laquelle la propriétéid
est uneshareId
. -
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ètreassetId
de la méthode sur la valeurshareId
obtenue à l'étape 1. -
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ètreassetId
de la méthode sur la valeurshareId
obtenue à l'étape 1. -
Appelez la méthode
assetRelationships.insert
pour identifier les enregistrements audio qui contiennent la composition. Dans la ressourceassetRelationship
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 valeurshareId
obtenue à l'étape 1. -
Si vous stockez un mappage de
viewIds
avecshareIds
, vous pouvez récupérerviewId
en appelant la méthodeassetRelationships.list
et en définissant le paramètreassetId
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 étantparentAssetId
. Dans cette relation, lechildAssetId
identifie laviewId
mappée aushareId
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
ouassetId
) spécifie une propriétéshareId
:- Si le paramètre
fetchMatchPolicy
est défini surmine
, 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 sureffective
, l'API renvoie une erreur400
.
- Si le paramètre
- Si l'ID de l'élément spécifie une
viewId
:- Si le paramètre
fetchMatchPolicy
est défini surmine
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 surmine
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 erreur400
. - Si le paramètre
fetchMatchPolicy
est défini sureffective
, 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.
- Si le paramètre
- Si l'ID de l'élément (paramètre
fetchMetadata
- Si l'ID de l'élément spécifie une
shareId
:- Si le paramètre
fetchMetadata
est défini surmine
, 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 sureffective
, l'API renvoie une erreur400
.
- Si le paramètre
- Si l'ID de l'élément spécifie une
viewId
:- Si le paramètre
fetchMetadata
est défini surmine
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 surmine
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 erreur400
. - Si le paramètre
fetchMetadata
est défini sureffective
, 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.
- Si le paramètre
- Si l'ID de l'élément spécifie une
fetchOwnership
- Si l'ID de l'élément spécifie une
shareId
:- Si le paramètre
fetchOwnership
est défini surmine
, 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 sureffective
, l'API renvoie une erreur400
.
- Si le paramètre
- Si l'ID de l'élément spécifie une
viewId
:- Si le paramètre
fetchOwnership
est défini surmine
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 surmine
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 erreur400
. - Si le paramètre
fetchOwnership
est défini sureffective
, 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.
- Si le paramètre
- Si l'ID de l'élément spécifie une
fetchOwnershipConflicts
- Si l'ID de l'élément spécifie
shareId
, l'API renvoie une erreur400
. - 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".
- Si l'ID de l'élément spécifie
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écifientshareId
, 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 unviewId
, et que le propriétaire de contenu qui autorise la requête ne possède qu'une seule part de la composition associée à ceviewId
, la requête API met à jour cette part de la composition. - Si le paramètre
assetId
et la propriétéid
spécifient unviewId
, et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à ceviewId
, la requête API renvoie une erreur400
.
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émentshareId
, 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émentviewId
, 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 uneshareId
, la requête API met à jour la règle de correspondance pour cette part de la composition. - Si le paramètre
assetId
spécifie uneviewId
et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à cetteviewId
, la requête API met à jour la règle de correspondance pour cette part de la composition. - Si le paramètre
assetId
spécifie uneviewId
et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à cetteviewId
, la requête API renvoie une erreur400
.
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écifieshareId
, la réponse de l'API contient une liste d'assets Enregistrement audio associés. La liste peut contenir plusieurs éléments. Dans chaque ressourceassetRelationship
, l'ID d'élément de l'enregistrement audio correspond àparentAssetId
, et l'ID àshareId
àchildAssetId
. - Si le paramètre
assetId
spécifie uneviewId
, la réponse de l'API identifie l'enregistrement audio associé à cetteviewId
. 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 ressourceassetRelationship
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.
- Si l'ID d'élément de l'enregistrement audio est le
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
serashareId
.
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 uneviewId
, la réponse de l'API contient une liste de ressourcesassetShare
. 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 unviewId
est mappé à plusieursshareIds
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 uneshareId
, la réponse de l'API contient une liste de ressourcesassetShare
. 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éponse400
. -
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émentshareId
, 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émentviewId
, 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 uneshareId
, 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 uneviewId
et que le propriétaire de contenu qui autorise la demande ne possède qu'une seule part de la composition associée à cetteviewId
, 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 uneviewId
et que le propriétaire de contenu qui autorise la requête possède plusieurs parts de la composition associées à cetteviewId
, la requête API renvoie une erreur400
.
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.