Eseguire la migrazione dai feed XML all'API Content ID

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 non visualizzi l'API YouTube Content ID tra i servizi elencati nella console API di Google, visita il Centro assistenza YouTube per scoprire di più sul Programma partner di YouTube.

Questa guida spiega in che modo i partner per i contenuti di YouTube possono eseguire la migrazione dai feed di contenuti XML all'API di YouTube Content ID per importare i contenuti nel sistema di gestione dei diritti di YouTube.

Panoramica

Per sfruttare il sistema di gestione dei diritti di Content ID di YouTube, devi fornire a YouTube i metadati, le informazioni sulla proprietà, le impostazioni delle norme e il materiale di riferimento per le tue risorse.

YouTube offre una varietà di opzioni per caricare i dati delle tue risorse. I partner che pubblicano regolarmente molti contenuti utilizzano spesso un metodo di caricamento collettivo, specificando le informazioni sulle risorse tramite il feed DDEX di YouTube o un modello di foglio di lavoro fornito da YouTube. In alternativa, l'API YouTube Content ID fornisce un controllo più granulare sulla procedura di caricamento.

Utilizzando l'API, puoi creare risorse e altre risorse una alla volta, a differenza dell'elaborazione batch di feed XML e fogli di lavoro. L'approccio individuale dell'API può comportare caricamenti più rapidi e affidabili. Gestisci il processo di caricamento in modo transazionale, monitorando l'efficacia delle singole azioni e reagendo immediatamente a eventuali problemi che si presentano. Puoi aggiornare il tuo sistema di gestione dei contenuti con gli ID generati da YouTube non appena diventano disponibili, anziché utilizzare un processo batch di post-elaborazione.

Questo documento descrive come utilizzare l'API Content ID di YouTube per definire le risorse nel sistema di gestione dei diritti di YouTube. Si presuppone che tu stia attualmente definendo le tue risorse utilizzando il feed DDEX di YouTube e spiega come ricreare la funzionalità del feed di contenuti XML utilizzando l'API. In particolare, utilizza un feed di contenuti XML di esempio e identifica i comandi API che ottengono lo stesso effetto, utilizzando la libreria client Python.

Modalità di invio dei dati delle risorse a YouTube

Il risultato finale dell'utilizzo del feed di contenuti XML o dell'API Content ID è lo stesso: crei (o aggiorni) le risorse di gestione dei diritti di YouTube nel tuo account partner. In alcuni casi, crei (o aggiorni) anche i video di YouTube.

Il feed di contenuti XML e l'API si approcciano all'attività in modo diverso. Con il feed di contenuti XML, crei un singolo file che contiene tutte le informazioni sulle risorse e sulle loro relazioni. YouTube utilizza il feed come progetto per creare le risorse effettive durante la procedura di caricamento in gruppo. L'API consente di creare le risorse una alla volta anziché in batch. Puoi monitorare l'avanzamento e l'esito positivo di ogni singola risorsa e chiamata API.

Quando crei risorse direttamente utilizzando metodi API, devi eseguire in modo esplicito determinate azioni che vengono gestite in background dal processo di caricamento in gruppo di YouTube. In particolare, devi caricare i file multimediali e risolvere i problemi (riprovando a eseguire le azioni o segnalando gli errori). Devi inoltre eseguire le azioni nell'ordine corretto; ad esempio, non potrai rivendicare un video prima di averlo creato.

Ciascuno degli elementi di livello principale nel formato del feed di contenuti XML di YouTube corrisponde a una risorsa (o proprietà della risorsa) che crei utilizzando le API di YouTube.

Elementi XML e risorse API corrispondenti
<asset> asset
<file> videos.fileDetails (dall'API YouTube Data) o
thumbnail (dall'API YouTube Data) oppure
reference
<ownership> ownership
<rights_admin> assetMatchPolicy (per le norme di corrispondenza)
claims.policy (per le norme di utilizzo)
<rights_policy> policy
<video> videos (dall'API YouTube Data)
<video_breaks> videoAdvertisingOption.adbreaks[ ]
<ad_policy> videoAdvertisingOption
<claim> claim
<playlist> playlist (dall'API YouTube Data)
<relationship> Diversi

Nota:l'API YouTube Content ID attualmente non supporta i file di sottotitoli, i trailer o i file di artwork degli album.

Il trattamento degli elementi <relationship> illustra bene la differenza tra il feed XML e l'API.

  • Un elemento XML <relationship> indica che esiste una relazione tra gli elementi <item> e <related_item>, ma non ne evidenzia la natura. La procedura di caricamento di YouTube deduce la corretta relazione dai tipi di articoli. Ad esempio, una relazione tra una risorsa e un video indica che YouTube deve utilizzare il file video come riferimento per la risorsa, mentre una relazione tra una norma pubblicitaria e un video stabilisce la norma per il video.

  • L'API YouTube Content ID ti consente di utilizzare risorse API specifiche che stabiliscono in modo esplicito la relazione adeguata. Per utilizzare un video come riferimento per una risorsa, devi creare una risorsa reference. Per impostare le norme relative agli annunci per un video, devi creare una risorsa videoAdvertisingOptions. L'asset deve esistere prima di poterne impostare le proprietà.

Caricare i dati degli asset tramite uno script

Per caricare i dati degli asset utilizzando le API, devi scrivere uno script che possa inviare richieste API, caricare file e creare risorse per la gestione dei diritti di YouTube. Questa sezione fornisce un tutorial per la scrittura dello script.

I passaggi principali sono:

  1. Crea uno script di base che utilizzi le API di YouTube.
  2. Aggiungi il codice per il caricamento di file multimediali.
  3. Aggiungere codice che crea risorse per la gestione dei diritti.
  4. Operazionalizza lo script in modo che funzioni con il tuo sistema di distribuzione dei contenuti.

Alla fine del documento viene fornito un esempio di codice (escluso il passaggio 4). Sebbene il codice sia scritto in Python, sono disponibili anche librerie client per gli altri linguaggi di programmazione più diffusi.

Passaggio 1: effettua chiamate API

Il tutorial Inviare una prima richiesta spiega come scrivere uno script di base che invii le richieste all'API YouTube Content. Lo script di esempio di questo tutorial autentica l'utente, autorizza l'uso delle richieste API e crea risorse per interagire con l'API Content ID di YouTube.

Tale script funge da base per lo script utilizzato in questo esempio. Tuttavia, come indicato sopra, in questo esempio viene spiegato come creare e rivendicare i video di YouTube. Inoltre, per caricare i video di YouTube è necessario utilizzare l'API di dati di YouTube. Per consentire allo script del tutorial di accedere anche all'API di dati di YouTube, apporta queste due aggiunte:

  • Autorizza l'accesso alla funzionalità di caricamento nell'API di dati di YouTube aggiungendo il relativo URI al parametro scope nella chiamata flow_from_clientsecrets (dal passaggio 2 del tutorial).

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

  • Crea una risorsa per interagire con l'API di dati di YouTube (dal passaggio 3 del tutorial). 

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

Passaggio 2: carica i file video

Il passaggio successivo consiste nell'aggiungere una funzione per caricare i file video. Per la massima affidabilità, utilizzerai un protocollo di caricamento ripristinabile. Questo protocollo consente di riprendere un'operazione di caricamento dopo un'interruzione di rete o un altro errore di trasmissione, risparmiando tempo e larghezza di banda in caso di guasti di rete.

La guida Caricamento di un video nella documentazione dell'API YouTube Data fornisce un esempio di script di caricamento, upload_video.py. Aggiorna lo script di base dal passaggio 1 aggiungendo la funzione resumable_upload da upload_video.py. Devi anche aggiungere le istruzioni import e le definizioni delle variabili da cui dipende la funzione.

Passaggio 3: crea le risorse per la gestione dei diritti di YouTube

Una volta configurato il framework di base, puoi aggiungere il codice che crea gli asset, i video e le risorse associate di YouTube.

L'ordine in cui crei le risorse è importante. Ad esempio, devi creare una risorsa e caricare un video prima di poterne rivendicare la risorsa.

L'ordine generale delle operazioni per le risorse film, TV, video musicale e video web è il seguente:

  1. Crea la risorsa asset (assets.insert)
  2. Aggiorna la proprietà (ownership.update) e la norma di corrispondenza (assetMatchPolicy.update) della risorsa
  3. Crea la risorsa video (videos.insert), impostandone i metadati e caricando il file multimediale
  4. Aggiorna le norme relative agli annunci del video (videoAdvertisingOptions.update)
  5. Rivendica il video per conto della risorsa (claims.insert)
  6. Crea un riferimento per la risorsa utilizzando il video rivendicato (references.insert)

L'ordine generale delle operazioni per le registrazioni audio o le risorse di solo riferimento è lo stesso, omettendo i passaggi da 3 a 5:

  1. Crea la risorsa asset (assets.insert)
  2. Aggiorna la proprietà (ownership.update) e la norma di corrispondenza (assetMatchPolicy.update) della risorsa
  3. Crea un riferimento per l'asset (references.insert) e carica il file multimediale

Il resto di questa sezione fornisce dettagli su ciascuno di questi passaggi, confrontando il feed XML di esempio con il codice corrispondente nello script di esempio.

Passaggio 3.1: crea un asset

La prima chiamata è al metodo assets.insert dell'API. Corrisponde a questa parte del feed 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>

Per specificare questi valori in una risorsa asset, devi impostare i seguenti valori delle proprietà:

{
  "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."
  }
}

Estrai la proprietà id dalla risorsa restituita dall'API. Questa proprietà identifica l'ID risorsa assegnato da YouTube per identificare in modo univoco la risorsa. Questo valore è obbligatorio in diverse chiamate API successive e viene identificato come assetId più avanti in questa documentazione.

Passaggio 3.2: aggiorna la proprietà della risorsa

Dopo aver creato una risorsa, ne imposti la proprietà utilizzando il metodo ownership.update dell'API. Questo passaggio corrisponde a questa parte del feed XML:

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

Il file XML utilizza un tag <ownership> vuoto, che indica che detieni la proprietà dei contenuti a livello mondiale.

La tua richiesta API imposterà il parametro di richiesta assetId su assetId ottenuto nel passaggio 1. Verrà specificata anche una risorsa ownership con i valori delle proprietà mostrati di seguito:

  • assetId (parametro di richiesta): impostato sul valore assetId ottenuto nel passaggio 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": []
  ]
}

Queste proprietà indicano che il proprietario dei contenuti specificato (devi sostituire your_content_owner_name con il nome effettivo del proprietario dei contenuti) possiede il 100% (general[0].ratio) dei contenuti ovunque. Infatti, questa risorsa ownership indica che il proprietario possiede i contenuti ovunque, ad eccezione di (general[0].type) dell'elenco di territori fornito (general[0].territories), ma poiché il valore di quella proprietà è un elenco vuoto, nessun territorio è effettivamente escluso.

Passaggio 3.3: imposta la norma di corrispondenza della risorsa

Il sistema di gestione dei diritti di YouTube offre due modi per associare una norma di corrispondenza a una risorsa o una norma di utilizzo a un video rivendicato:

  • Utilizza un criterio salvato in precedenza. Con questo approccio, utilizzerai l'API per recuperare le norme salvate, trovare la norma che vuoi utilizzare e specificare il relativo ID univoco quando imposti la norma di corrispondenza di una risorsa o crei una rivendicazione.

  • Definisci una risorsa policy durante la creazione della risorsa o della rivendicazione. In questo caso, la risorsa della norma non viene salvata e, pertanto, non può essere applicata ad altre risorse o rivendicazioni.

Ti consigliamo di utilizzare il primo approccio, che si basa sulle norme salvate. Un importante vantaggio di questo approccio è che, se aggiorni una norma salvata, la modifica influisce automaticamente su tutte le risorse e le rivendicazioni che la utilizzano.

Tuttavia, gli esempi di codice in questo documento utilizzano il secondo approccio per impostare la norma di corrispondenza per il nuovo asset, utilizzando il metodo assetMatchPolicy.update dell'API. Questo documento utilizza anche il secondo approccio per impostare la norma di utilizzo, che viene definita quando il video viene rivendicato. Il documento utilizza il secondo approccio perché i nomi delle norme salvate possono variare da partner a partner. Questo approccio garantisce che lo stesso codice funzioni per tutti.

Questo passaggio corrisponde a questa parte del feed 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>

La tua richiesta API imposta il parametro assetId sul valore assetId ottenuto nel passaggio 1. Invia anche una risorsa assetMatchPolicy che imposta i valori delle proprietà elencati di seguito:

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

L'esempio seguente mostra come verrebbe creata la risorsa assetMatchPolicy se dovessi impostare una norma salvata come norma di corrispondenza di una risorsa. Il codice dovrebbe sostituire la stringa PolicyID con l'ID che identifica in modo univoco il criterio salvato.

{
  "policyId": "PolicyID"
}

Nota:il feed XML, come la pagina Norme di YouTube Content Manager, specifica le norme in base al nome. Per recuperare l'ID di un criterio salvato, utilizza il metodo policies.list. Gli ID norma variano da partner a partner, anche per le norme predefinite.

Passaggio 3.4: crea una risorsa video e carica il file multimediale

Puoi caricare il video utilizzando il metodo videos.insert dell'API di dati. La guida Caricamenti ripristinabili identifica le chiamate HTTP che eseguiresti per caricare i video utilizzando un processo di caricamento ripristinabile. Inoltre, diverse delle nostre librerie client API supportano anche i caricamenti ripristinabili. Il codice campione riportato di seguito utilizza un processo di caricamento ripristinabile con la libreria client Python delle API di Google.

Questo passaggio corrisponde a questa parte del feed 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>

Se stai scrivendo codice personalizzato per effettuare le chiamate API, invia una richiesta iniziale che crea la risorsa video e restituisce un URL di caricamento, quindi invia una seconda richiesta di caricamento dei dati del file binario video su quell'URL. Se utilizzi la libreria client Python (come nell'esempio), invii la risorsa video e i dati del file binario video nella stessa richiesta.

Per creare il video descritto nell'esempio XML, la richiesta API imposterebbe il valore del parametro part su snippet,status e la risorsa video nel corpo della richiesta imposterebbe le seguenti proprietà. Il valore snippet.categoryId (24) corrisponde alla categoria Entertainment, ovvero la categoria associata al video nel feed XML. Le categorie di video vengono trattate in modo più dettagliato nelle appendici.

{
  "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"
  }
}

Nota: ti consigliamo di impostare lo stato della privacy di un video su private quando carichi il video e di aggiornarlo a public più avanti durante la procedura. Se preferisci caricare il video come video pubblico, imposta la proprietà status.privacyStatus su public.

Estrai la proprietà id dalla risorsa restituita dall'API. Questa proprietà identifica l'ID video assegnato da YouTube per identificare in modo univoco il video. Questo valore è obbligatorio in diverse chiamate API successive e viene identificato come videoId più avanti in questa documentazione.

Passaggio 3.5: esegui un sondaggio nell'API di dati per determinare quando il video è stato elaborato

Determinate azioni, come la creazione di un riferimento, richiedono che YouTube abbia terminato l'elaborazione del video. Per questo motivo, il passaggio successivo dello script consiste nel garantire che il caricamento del video sia completo.

Per verificare lo stato del caricamento, chiama il metodo videos.list dell'API di dati e imposta i seguenti parametri di richiesta:

  • id: videoId (dal passaggio precedente)
  • part: "processingDetails"

L'API restituisce un elenco di video risorse (contenenti esattamente una risorsa) e devi verificare il valore della proprietà processingDetails.processingStatus di quella risorsa per determinare se YouTube sta ancora elaborando il video. Il valore della proprietà passerà a un valore diverso da processing, ad esempio succeeded o failed, quando YouTube avrà terminato l'elaborazione del video.

Il codice campione chiama il metodo videos.list ogni 12 secondi per determinare se l'elaborazione del video è terminata. Questo controllo dello stato non corrisponde direttamente ad alcun elemento del file XML. rappresenta un'azione che un caricamento in batch gestisce in modo implicito quando elabora il codice XML.

Passaggio 3.6: imposta le norme relative agli annunci

Una volta che YouTube ha elaborato il video, puoi aggiornare le impostazioni degli annunci della risorsa video. Chiama il metodo videoAdvertisingOptions.update dell'API Content ID per impostare le norme relative agli annunci per il video. Questa azione corrisponde a questa parte del feed 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 norma mostrata in questo esempio consente a YouTube di mostrare TrueView annunci in-stream o annunci in overlay, inclusi quelli di tipo "lungo" Annunci di 30 secondi, all'inizio (pre-roll) o alla fine (post-roll) del video.

Per impostare le norme relative agli annunci, invia una richiesta che imposti il parametro videoId sul valore videoId ottenuto in precedenza. Il corpo della richiesta è una risorsa videoAdvertisingOptions che imposta le proprietà mostrate di seguito:

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

Passaggio 3.7: rivendica il video

In questo passaggio, rivendichi il video che hai caricato e imposti la norma di utilizzo del video richiamando il metodo claims.insert dell'API Content ID. Questo passaggio corrisponde a questa parte del feed 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]"/>

Come per la norma di corrispondenza della risorsa, lo script di esempio definisce una norma una tantum anziché associare al video una norma salvata. Tuttavia, come discusso in precedenza, puoi e ti invitiamo a utilizzare le norme salvate quando imposti le norme di utilizzo e di corrispondenza.

Nella risorsa claim che invii con la richiesta, imposta le proprietà mostrate nella risorsa di seguito. Tieni presente che le stringhe assetId e videoId devono essere sostituite con i valori ottenuti dallo script nei passaggi precedenti.

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

Estrai la proprietà id dalla risorsa restituita dall'API. Questa proprietà identifica l'ID rivendicazione assegnato da YouTube per identificare in modo univoco la rivendicazione. Questo valore è obbligatorio per le chiamate API successive ed è identificato come claimId più avanti in questa documentazione.

Passaggio 3.8: crea un riferimento

Utilizza il metodo references.insert dell'API Content ID per creare un riferimento per il sistema Content ID. Puoi creare un riferimento utilizzando un video rivendicato come contenuto di riferimento oppure caricare un file di riferimento durante la chiamata API. Se crei un riferimento da un video rivendicato, come avviene nello script di esempio, la rivendicazione deve già esistere.

Nella richiesta API, imposta il parametro di richiesta claimId sul valore claimid ottenuto nel passaggio precedente. Invia anche una risorsa reference che imposti le proprietà mostrate di seguito:

{
  "contentType": "audiovisual"
}

Per creare una risorsa di solo riferimento (senza video rivendicato), apporta le seguenti modifiche alla richiesta riportata sopra:

  1. Ometti il parametro di richiesta claimId
  2. Aggiungi la proprietà assetId alla risorsa reference caricata.
  3. Carica il file di riferimento come media_body della richiesta API.

Passaggio 3.9: rendi pubblico il video

Se hai seguito le best practice e hai impostato lo stato della privacy del tuo video su private al momento della creazione, puoi modificarlo in public al termine della procedura di caricamento. Utilizza i metodi videos.list e videos.update della YouTube Data API per recuperare e aggiornare la risorsa video per il video appena caricato.

Innanzitutto, chiama il metodo videos.list dell'API di dati con i seguenti parametri di richiesta:

  • part=status
  • id=videoId

Questo metodo restituisce un elenco contenente una risorsa, che descrive il video con il videoId specificato. Modifica il valore della proprietà status.privacyStatus della risorsa in public, quindi chiama il metodo videos.update dell'API di dati. Imposta il seguente parametro di richiesta:

  • part=status

Il corpo della richiesta è la risorsa video modificata.

Passaggio 4: integra con il tuo sistema di importazione dei contenuti

Il codice campione nelle appendici include i metadati specifici delle risorse direttamente nello script. In pratica, ti consigliamo di integrare lo script con il tuo sistema di gestione dei contenuti. Per un sistema di importazione dei contenuti più completo, potresti aggiungere passaggi quali:

  • Conduci un sondaggio al tuo sistema di gestione dei contenuti per identificare le risorse che devono essere aggiunte o aggiornate.
  • Recupera i metadati delle risorse dal sistema di gestione dei contenuti.
  • Aggiorna il sistema di gestione dei contenuti con gli ID forniti da YouTube per le risorse, i video, i riferimenti e le rivendicazioni create, nonché con timestamp per registrare l'ultimo aggiornamento delle risorse.

Appendice

File XML di esempio del feed

<?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>

Script di esempio

Il codice campione utilizza la libreria client Python delle API di 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)

Altre azioni dell'API

Recupera un elenco di categorie di video utilizzando l'API di dati

Il codice di esempio imposta il valore della proprietà snippet.categoryID su 24, che corrisponde a "Entertainment" genere. Se vuoi che lo script cerchi l'ID per un determinato genere (anziché l'hardcoded degli ID categoria), devi chiamare il metodo videoCategories.list dell'API di dati e impostare i seguenti parametri di richiesta:

  • part=snippet
  • regionCode=US (puoi impostare regionCode su un valore diverso per recuperare le categorie dei video per un altro paese)

Per ogni risorsa videoCategory nella risposta dell'API, controllerai il valore della proprietà snippet.title per identificare un nome di categoria ed estrai la proprietà id dalla categoria che ti interessa. Ecco come si presenta la risorsa videoCategory per "Intrattenimento" categoria:

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