Nota:l'API YouTube Content ID è destinata ai partner per i contenuti di YouTube e non è accessibile a tutti gli sviluppatori o a tutti gli utenti di YouTube. Se l'API YouTube Content ID non rientra tra i servizi elencati nella console API di Google, visita il Centro assistenza YouTube per scoprire di più sul Programma partner di YouTube.
Nota: le informazioni contenute in questa guida si applicano specificamente alle risorse di composizione.
Nel sistema di gestione dei diritti di YouTube, una risorsa rappresenta una proprietà intellettuale. YouTube riconosce diversi tipi di risorse, come film, video musicali, registrazioni audio e composizioni.
Tuttavia, a causa della complessa natura della proprietà e dei diritti della composizione, YouTube utilizza un modello di risorse a due livelli per le risorse di composizione. Il modello è progettato per tenere conto di quanto segue:
- Ogni registrazione audio è associata a una composizione.
- I proprietari dei contenuti spesso devono applicare la proprietà dei diritti di pubblicazione per lo stesso brano o la stessa composizione a diverse registrazioni audio.
Questo documento fornisce una panoramica del modello di risorse di composizione di YouTube. Spiega inoltre come vengono utilizzati i due tipi di risorse di composizione nei metodi dell'API YouTube Content ID.
Informazioni sul modello di asset di composizione
Il modello di risorse di YouTube definisce due diverse rappresentazioni delle risorse di composizione:
-
Una quota di composizione rappresenta le informazioni fornite da un determinato editore su una risorsa di composizione. Pertanto, una quota della composizione identifica solo i metadati, la proprietà e i dati sulle norme che quel singolo editore fornisce per la composizione.
Una quota della composizione può essere associata a molte registrazioni audio.
-
Una visualizzazione di composizione rappresenta la risorsa composizione incorporata in una registrazione audio. Ogni registrazione audio corrisponde a una sola visualizzazione di composizione, mentre questa rappresenta l'insieme canonico di informazioni che YouTube mostra su una composizione. I metadati, i dati sulla proprietà e la norma della vista della composizione vengono determinati utilizzando i dati di tutte le risorse quota della composizione associate.
Una visualizzazione della composizione può essere mappata a zero o più quote della composizione. Tuttavia, una visualizzazione della composizione viene mappata a più quote della composizione solo quando una composizione ha più proprietari.
Tieni presente che è possibile che un singolo proprietario dei contenuti che utilizzi l'API rappresenti più proprietari di una composizione e, pertanto, possieda più quote della composizione. Ad esempio, un aggregatore di diritti digitali potrebbe ottenere i diritti sulla stessa composizione da diverse parti in territori diversi. L'aggregatore avrà entità distinte che rappresentano questi diritti, mappati a diverse quote della composizione nel modello di YouTube. Le diverse quote della composizione potrebbero essere comunque collegate alle stesse viste della composizione.
Il seguente diagramma illustra questo modello. Nel diagramma:
- Le cerchie sono registrazioni audio.
- I quadrati sono viste di composizione.
- I triangoli sono quote della composizione. Ogni colore del triangolo rappresenta un proprietario dei contenuti diverso. I piccoli triangoli all'interno dei quadrati mostrano quali dati vengono uniti per generare l'insieme canonico di informazioni che YouTube mostra su una composizione. YouTube usa questi dati per calcolare la proprietà e la norma di una composizione.
Due tipi di ID risorsa
YouTube assegna degli ID alle quote della composizione e alle visualizzazioni della composizione ed entrambe sono considerate ID risorsa. Tuttavia, non sono intercambiabili nell'API. Alla luce di questo, nel resto del documento vengono utilizzati i termini shareId
e viewId
per fare riferimento rispettivamente agli ID assegnati alle quote della composizione e alle visualizzazioni della composizione.
In generale, quando recuperi o aggiorni le informazioni che fornisci su una risorsa, utilizzerai shareId
. Se stai recuperando l'insieme canonico di informazioni che YouTube mostra su una risorsa, utilizzerai viewId
.
Se torni al diagramma nella sezione precedente, noterai che le registrazioni audio e le visualizzazioni delle composizioni sono contrassegnate da numeri (SR1, CV1 e così via). I numeri riflettono la relazione 1:1 tra registrazioni audio e visualizzazioni della composizione. Quindi, se vuoi recuperare l'insieme canonico di informazioni sulla composizione in una determinata registrazione audio, devi utilizzare viewId
per quella composizione.
Le quote della composizione, invece, sono contrassegnate da lettere (CSb e così via). Le lettere rappresentano diversi proprietari dei contenuti. Quindi, se sei il proprietario dei contenuti verdi e vuoi recuperare i metadati o i dati sulla proprietà che hai fornito per una risorsa di composizione, devi utilizzare shareId
per recuperare queste informazioni.
Utilizzare gli ID risorsa nei metodi API
Nella parte restante di questo documento viene spiegato in che modo i singoli metodi API gestiscono shareIds
e viewIds
quando questi ID vengono utilizzati come valori di parametri o proprietà. Poiché i metodi dell'API sono elencati in ordine alfabetico, potrebbe essere utile seguire prima i passaggi tipici associati alla creazione di una risorsa composizione e al suo collegamento a una registrazione audio.
-
Chiama il metodo
assets.insert
per creare una risorsa di composizione. La risposta API è una risorsaasset
in cui la proprietàid
è unshareId
. -
Chiama il metodo
ownership.update
per impostare i dati di proprietà per la quota della composizione. Imposta il parametroassetId
del metodo sul valoreshareId
ottenuto nel passaggio 1. -
Richiama il metodo
assetMatchPolicy.update
per impostare i dati dei criteri per la quota della composizione. La norma viene applicata ai video rivendicati che contengono la composizione. Imposta il parametroassetId
del metodo sul valoreshareId
ottenuto nel passaggio 1. -
Richiama il metodo
assetRelationships.insert
per identificare le registrazioni audio che contengono la composizione. Nella risorsaassetRelationship
che stai inserendo, imposta la proprietàparentAssetId
sull'ID risorsa della registrazione audio. Imposta la proprietàchildAssetId
sul valoreshareId
ottenuto nel passaggio 1. -
Se memorizzi una mappatura di
viewIds
ashareIds
, puoi recuperareviewId
chiamando il metodoassetRelationships.list
e impostando il parametroassetId
sull'ID risorsa della registrazione audio. Una relazione nel set di risultati identificherà l'ID risorsa della registrazione audio comeparentAssetId
. In questa relazione,childAssetId
identifica ilviewId
che corrisponde allashareId
ottenuta nel passaggio 1.
Dopo aver creato la risorsa, puoi utilizzare uno dei metodi descritti nel resto di questo documento per recuperare informazioni, aggiornarla o eliminarla.
assets.get/assets.list
I metodi assets.get
e assets.list
consentono di recuperare informazioni su una risorsa o un elenco di risorse. Entrambi i metodi supportano lo stesso insieme di parametri di richiesta.
Tre di questi parametri, fetchMatchPolicy
, fetchMetadata
e fetchOwnership
, utilizzano i valori effective
e mine
per indicare se vuoi recuperare l'insieme canonico di dati sulla risorsa o se vuoi recuperare i dati che hai fornito sulla risorsa. Questi valori sono una traccia del vecchio modello di risorsa di composizione di YouTube, che trattava una visualizzazione della composizione e le relative quote della composizione come una singola entità.
Tuttavia, i valori sono ancora supportati nel modello a due livelli e i contenuti della risposta dell'API dipendono dal valore del parametro e dal fatto che le richieste forniscano shareIds
o viewIds
. Tieni presente che il metodo assets.get
utilizza il parametro assetId
per specificare l'ID asset, mentre il metodo assets.list
utilizza il parametro id
.
L'elenco riportato di seguito spiega in che modo i valori dei parametri di richiesta influiscono sui contenuti delle risposte dell'API per questi due metodi.
fetchMatchPolicy
- Se l'ID risorsa (parametro
id
oassetId
) specifica unshareId
:- Se il parametro
fetchMatchPolicy
èmine
, la risposta dell'API contiene la norma secondo cui il proprietario dei contenuti autorizza la richiesta API impostata per la quota della composizione. - Se il parametro
fetchMatchPolicy
èeffective
, l'API restituisce un errore400
.
- Se il parametro
- Se l'ID risorsa specifica un
viewId
:- Se il parametro
fetchMatchPolicy
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede una sola quota della composizione collegata all'ID vista, l'API restituisce la norma di corrispondenza impostata per tale quota della composizione. - Se il parametro
fetchMatchPolicy
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate all'ID visualizzazione, l'API restituisce un errore400
. - Se il parametro
fetchMatchPolicy
èeffective
, l'API restituisce la norma di corrispondenza canonica per la visualizzazione di composizione. Questa norma di corrispondenza prende in considerazione le norme di corrispondenza di tutte le quote della composizione collegate alviewId
, indipendentemente dai proprietari dei contenuti che possiedono le quote.
- Se il parametro
- Se l'ID risorsa (parametro
fetchMetadata
- Se l'ID risorsa specifica un
shareId
:- Se il parametro
fetchMetadata
èmine
, la risposta dell'API contiene i metadati della risorsa che il proprietario dei contenuti autorizza la richiesta API impostata per la quota della composizione. - Se il parametro
fetchMetadata
èeffective
, l'API restituisce un errore400
.
- Se il parametro
- Se l'ID risorsa specifica un
viewId
:- Se il parametro
fetchMetadata
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede una sola quota della composizione collegata all'ID visualizzazione, l'API restituisce i metadati impostati per quella quota della composizione. - Se il parametro
fetchMetadata
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate all'ID visualizzazione, l'API restituisce un errore400
. - Se il parametro
fetchMetadata
èeffective
, l'API restituisce l'insieme canonico di metadati per la visualizzazione della composizione. Questi metadati prendono in considerazione i metadati della risorsa forniti per tutte le quote della composizione collegate alviewId
, indipendentemente dai proprietari dei contenuti che possiedono le quote.
- Se il parametro
- Se l'ID risorsa specifica un
fetchOwnership
- Se l'ID risorsa specifica un
shareId
:- Se il parametro
fetchOwnership
èmine
, la risposta dell'API contiene i dati sulla proprietà che il proprietario dei contenuti ha impostato per la richiesta API per la quota della composizione. - Se il parametro
fetchOwnership
èeffective
, l'API restituisce un errore400
.
- Se il parametro
- Se l'ID risorsa specifica un
viewId
:- Se il parametro
fetchOwnership
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede una sola quota della composizione collegata all'ID vista, l'API restituisce i dati di proprietà impostati per quella quota della composizione. - Se il parametro
fetchOwnership
èmine
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate all'ID visualizzazione, l'API restituisce un errore400
. - Se il parametro
fetchOwnership
èeffective
, l'API restituisce i dati di proprietà canonici per la visualizzazione della composizione. Questi dati prendono in considerazione i dati sulla proprietà di tutte le quote della composizione collegate alviewId
, indipendentemente dai proprietari dei contenuti che detengono tali quote.
- Se il parametro
- Se l'ID risorsa specifica un
fetchOwnershipConflicts
- Se l'ID risorsa specifica un
shareId
, l'API restituisce una risposta di errore400
. - Se l'ID risorsa specifica un
viewId
, l'API restituisce un elenco di conflitti di proprietà associati alla visualizzazione della composizione.
- Se l'ID risorsa specifica un
assets.insert
Questo metodo crea una risorsa asset
e YouTube assegna un ID per identificarla in modo univoco. Questo ID, restituito come valore della proprietà id
nella risposta dell'API, è un shareId
.
Nota: ti ricordiamo che shareIds
e viewIds
vengono utilizzati solo per gli asset di composizione. Altri tipi di asset non utilizzano un modello a due livelli per la gestione dei dati degli asset.
assets.update e assets.patch
Questi metodi aggiornano i metadati di una risorsa. In entrambe le richieste, il parametro assetId
identifica l'asset da aggiornare. Inoltre, in entrambe le richieste, il corpo della richiesta è una risorsa asset
in cui il valore della proprietà id
deve corrispondere al valore del parametro assetId
.
- Se il parametro
assetId
e la proprietàid
specificano unshareId
, la richiesta API aggiorna la quota della composizione specificata. - Se il parametro
assetId
e la proprietàid
specificano unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a taleviewId
, la richiesta API aggiorna questa quota. - Se il parametro
assetId
e la proprietàid
specificano unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a taleviewId
, la richiesta API restituisce un errore400
.
assetMatchPolicy.get
Questo metodo restituisce la norma di corrispondenza definita per una specifica risorsa. Il parametro assetId
della richiesta identifica l'asset.
- Se il parametro
assetId
specifica unshareId
, la risposta dell'API contiene i metadati della risorsa che il proprietario dei contenuti autorizza la richiesta API impostata per la quota della composizione. - Se il parametro
assetId
specifica unviewId
, l'API restituisce l'insieme canonico di metadati per la visualizzazione della composizione. Questi metadati prendono in considerazione i metadati della risorsa forniti per tutte le quote della composizione collegate alviewId
, indipendentemente dai proprietari dei contenuti che possiedono le quote.
assetMatchPolicy.update e assetMatchPolicy.patch
Questi metodi aggiornano la norma di corrispondenza per una risorsa specificata. Il parametro assetId
della richiesta identifica l'asset.
- Se il parametro
assetId
specifica un valoreshareId
, la richiesta API aggiorna la norma di corrispondenza per la quota della composizione. - Se il parametro
assetId
specifica unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a taleviewId
, la richiesta API aggiorna la norma di corrispondenza per quella quota della composizione. - Se il parametro
assetId
specifica unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a quelviewId
, la richiesta API restituisce un errore400
.
assetRelationships.list
Questo metodo restituisce un elenco di relazioni tra risorse relative a una risorsa specificata. Il parametro assetId
della richiesta identifica l'asset.
- Se il parametro
assetId
specifica un valoreshareId
, la risposta dell'API contiene un elenco di risorse registrazione audio collegate. L'elenco può contenere più elementi. In ogni risorsaassetRelationship
, l'ID risorsa della registrazione audio èparentAssetId
eshareId
èchildAssetId
. - Se il parametro
assetId
specifica unviewId
, la risposta dell'API identifica la registrazione audio collegata a quelviewId
. La risposta contiene al massimo una risorsa. - Se il parametro
assetId
identifica una risorsa registrazione audio, la risposta dell'API può contenere più relazioni.- Se l'ID risorsa della registrazione audio è
parentAssetId
in una risorsaassetRelationship
restituita,childAssetId
identifica la visualizzazione della composizione (viewId
) collegata a quella registrazione audio. Ogni registrazione audio ha esattamente una di queste relazioni. - Se l'ID risorsa della registrazione audio è
childAssetId
,parentAssetId
identifica un video contenente la registrazione audio, ad esempio un video musicale o un video art track. Ogni registrazione audio può avere più relazioni di questo tipo.
- Se l'ID risorsa della registrazione audio è
assetRelationships.insert
Questo metodo crea una relazione tra due asset. Questo metodo deve essere chiamato per indicare che possiedi una quota della composizione collegata a una registrazione audio.
Nella risorsa assetRelationship
del corpo della richiesta, imposta la proprietà parentAssetId
sull'ID risorsa della registrazione audio. Imposta la proprietà childAssetId
su shareId
.
assetSearch.list
Questo metodo consente di cercare le risorse in base ai relativi metadati. La risposta API contiene un elenco di risorse assetSearch
, in cui la proprietà id
di ogni risorsa identifica un ID asset. Il valore della proprietà id
è, in realtà, un ID risorsa.
- Se la risorsa
assetSearch
identifica una composizione, il valore della proprietàid
saràshareId
.
assetShares.list
Questo metodo restituisce una mappatura delle viste della composizione alle quote della composizione. Il parametro assetId
della richiesta può specificare un viewId
o un shareId
.
-
Se il parametro
assetId
specifica unviewId
, la risposta dell'API contiene un elenco di risorseassetShare
. Ogni risorsa identifica una quota della composizione che è collegata alla visualizzazione della composizione specificata e che è di proprietà del proprietario dei contenuti che autorizza la richiesta.La risposta dell'API può contenere più risorse
assetShare
. Il caso d'uso comune in cui unviewId
viene associato a piùshareIds
di proprietà dello stesso proprietario dei contenuti è descritto nella sezione Informazioni sul modello di risorsa di composizione di questo documento. -
Se il parametro
assetId
specifica unshareId
, la risposta dell'API contiene un elenco di risorseassetShare
. Ogni risorsa identifica una vista della composizione associata alla quota della composizione specificata. La risposta conterrà una risorsa per ogni registrazione audio a cui è collegata la quota della composizione. (ogni registrazione audio è collegata a una sola visualizzazione della composizione).
claimSearch.list
Questo metodo restituisce un elenco di rivendicazioni che corrispondono a criteri di ricerca specificati. Il parametro assetId
del metodo ti consente di cercare le rivendicazioni associate a una determinata risorsa.
-
Se la richiesta API specifica un valore
shareId
, l'API restituisce un codice di risposta400
. -
Se la richiesta API specifica un
viewId
, l'API restituisce un elenco di rivendicazioni associate alla visualizzazione della composizione specificata, che viene mappato a una sola risorsa registrazione audio.
metadataHistory.list
Questo metodo restituisce un elenco di tutti i metadati forniti per una risorsa, indipendentemente dal proprietario dei contenuti che ha fornito i dati. Il parametro assetId
della richiesta identifica l'asset per il quale vengono recuperati i dati.
-
Se la richiesta API specifica un valore
shareId
, l'API restituisce l'insieme di metadati più recente per quella quota della composizione. -
Se la richiesta API specifica un valore
viewId
, l'API restituisce un elenco in cui ogni voce contiene l'ultimo insieme di metadati fornito per ogni quota della composizione collegata a quella vista della composizione.
ownership.get
Questo metodo restituisce i dati sulla proprietà definiti per una determinata risorsa. Il parametro assetId
della richiesta identifica l'asset.
- Se il parametro
assetId
specifica unshareId
, la risposta dell'API contiene i dati sulla proprietà che il proprietario dei contenuti ha impostato per la richiesta API per la quota della composizione. - Se il parametro
assetId
specifica unviewId
, l'API restituisce l'insieme canonico di dati sulla proprietà per la visualizzazione della composizione. La risposta sintetizza i dati sulla proprietà forniti per tutte le quote della composizione collegate alviewId
, indipendentemente dai proprietari dei contenuti che possiedono le quote.
property.update e ownership.patch
Questi metodi consentono di aggiornare i dati sulla proprietà di una risorsa specificata. Il parametro assetId
della richiesta identifica l'asset.
- Se il parametro
assetId
specifica un valoreshareId
, la richiesta API aggiorna i dati di proprietà per quella quota della composizione. - Se il parametro
assetId
specifica unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a taleviewId
, la richiesta API aggiornerà i dati di proprietà per quella quota della composizione. - Se il parametro
assetId
specifica unviewId
e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a quelviewId
, la richiesta API restituisce un errore400
.
ownershipHistory.list
Questo metodo restituisce un elenco di tutti i dati sulla proprietà forniti per una risorsa, indipendentemente dal proprietario dei contenuti che ha fornito i dati. Il parametro assetId
della richiesta identifica l'asset per il quale vengono recuperati i dati.
-
Se la richiesta API specifica un
shareId
, l'API restituisce il set più recente di dati di proprietà per quella quota della composizione. -
Se la richiesta API specifica un
viewId
, l'API restituisce un elenco in cui ogni voce contiene l'ultimo set di dati di proprietà fornito per qualsiasi quota della composizione collegata a quella vista della composizione.