Gestione delle risorse della composizione

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.

Diagramma che mostra le relazioni tra registrazioni audio, visualizzazioni della composizione e quote della 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.

  1. Chiama il metodo assets.insert per creare una risorsa di composizione. La risposta API è una risorsa asset in cui la proprietà id è un shareId.

  2. Chiama il metodo ownership.update per impostare i dati di proprietà per la quota della composizione. Imposta il parametro assetId del metodo sul valore shareId ottenuto nel passaggio 1.

  3. 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 parametro assetId del metodo sul valore shareId ottenuto nel passaggio 1.

  4. Richiama il metodo assetRelationships.insert per identificare le registrazioni audio che contengono la composizione. Nella risorsa assetRelationship che stai inserendo, imposta la proprietà parentAssetId sull'ID risorsa della registrazione audio. Imposta la proprietà childAssetId sul valore shareId ottenuto nel passaggio 1.

  5. Se memorizzi una mappatura di viewIds a shareIds, puoi recuperare viewId chiamando il metodo assetRelationships.list e impostando il parametro assetId sull'ID risorsa della registrazione audio. Una relazione nel set di risultati identificherà l'ID risorsa della registrazione audio come parentAssetId. In questa relazione, childAssetId identifica il viewId che corrisponde alla shareId 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 o assetId) specifica un shareId:
      • 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 errore 400.
    • 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 errore 400.
      • 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 al viewId, indipendentemente dai proprietari dei contenuti che possiedono le quote.
  • 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 errore 400.
    • 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 errore 400.
      • 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 al viewId, indipendentemente dai proprietari dei contenuti che possiedono le quote.
  • 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 errore 400.
    • 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 errore 400.
      • 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 al viewId, indipendentemente dai proprietari dei contenuti che detengono tali quote.
  • fetchOwnershipConflicts
    • Se l'ID risorsa specifica un shareId, l'API restituisce una risposta di errore 400.
    • Se l'ID risorsa specifica un viewId, l'API restituisce un elenco di conflitti di proprietà associati alla visualizzazione della composizione.

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 un shareId, la richiesta API aggiorna la quota della composizione specificata.
  • Se il parametro assetId e la proprietà id specificano un viewId e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a tale viewId, la richiesta API aggiorna questa quota.
  • Se il parametro assetId e la proprietà id specificano un viewId e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a tale viewId, la richiesta API restituisce un errore 400.

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 un shareId, 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 un viewId, 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 al viewId, 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 valore shareId, la richiesta API aggiorna la norma di corrispondenza per la quota della composizione.
  • Se il parametro assetId specifica un viewId e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a tale viewId, la richiesta API aggiorna la norma di corrispondenza per quella quota della composizione.
  • Se il parametro assetId specifica un viewId e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a quel viewId, la richiesta API restituisce un errore 400.

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 valore shareId, la risposta dell'API contiene un elenco di risorse registrazione audio collegate. L'elenco può contenere più elementi. In ogni risorsa assetRelationship, l'ID risorsa della registrazione audio è parentAssetId e shareId è childAssetId.
  • Se il parametro assetId specifica un viewId, la risposta dell'API identifica la registrazione audio collegata a quel viewId. 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 risorsa assetRelationship 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.

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 un viewId, la risposta dell'API contiene un elenco di risorse assetShare. 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 un viewId 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 un shareId, la risposta dell'API contiene un elenco di risorse assetShare. 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 risposta 400.

  • 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 un shareId, 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 un viewId, 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 al viewId, 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 valore shareId, la richiesta API aggiorna i dati di proprietà per quella quota della composizione.
  • Se il parametro assetId specifica un viewId e il proprietario dei contenuti che autorizza la richiesta possiede solo una quota della composizione collegata a tale viewId, la richiesta API aggiornerà i dati di proprietà per quella quota della composizione.
  • Se il parametro assetId specifica un viewId e il proprietario dei contenuti che autorizza la richiesta possiede più quote della composizione collegate a quel viewId, la richiesta API restituisce un errore 400.

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.