Dopo aver mosso i primi passi nell'utilizzo del web service offerto da Youtube, siamo in grado di approfondire l'argomento per sfruttare alcune delle più interessanti funzionalità offerte dal servizio stesso. Vanno ricordate le indicazioni proposte nell'articolo precedente riguardanti gli strumenti necessari: una versione di PHP superiore alla 5.1.4 ed alcune classi dello Zend Framework che costituiscono, in particolare il package Zend_GData e la classe Loader, che saranno i nostri strumenti per interfacciarci con l'API di Youtube. Va inoltre ricordata la procedura di autenticazione, proposta nell'articolo precedente e riutilizzata nei prossimi paragrafi.
Operazioni preliminari
Come spiegato nel precedente articolo, è importante all'inizio di ciascuno script caricare le classi necessarie ed inizializzare un'istanza della classe Zend_Gdata_YouTube. Supponiamo di includere il codice necessario in un file che chiameremo youtube_setup.php:
require_once 'Zend/Loader.php'; // verificare che la cartella Zend sia nell'include_path
Zend_Loader::loadClass('Zend_Gdata_YouTube');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');
// URL per l'autenticazione
$authenticationURL= 'https://www.google.com/youtube/accounts/ClientLogin';
// Credo un client http per il login
$httpClient = Zend_Gdata_ClientLogin::getHttpClient(
$username = 'mio-account@gmail.com',
$password = 'mia-password',
$service = 'youtube',
$client = null,
$source = 'Nome applicazione',
$loginToken = null,
$loginCaptcha = null,
$authenticationURL);
// Un breve nome per l'applicazione
$applicationId = 'Video uploader v1';
// Client ID e developer key
$clientId = 'mio-client-id';
$developerKey = 'mio-developer-key';
// Creo quindi l'oggetto $youtube
$youtube = new Zend_Gdata_YouTube($httpClient, $applicationId, $clientId, $developerKey);Le prime righe di codice ci garantiscono di caricare le classi necessarie, mediante lo Zend_Loader. Gli aspetti di autenticazione erano già stati accennati nel primo articolo, così come la procedura necessaria per ottenere una chiave da sviluppatore (developer key) da associare alla nostra applicazione. La riga finale ci consente di creare l'oggetto desiderato.
Nota sull'autenticazione: nel caso in cui il proprio account Google e l'account Youtube siano stati creati in momenti diversi, potrebbero non risultare collegati. Per collegarli è sufficiente effettuare l'accesso sul sito youtube.com utilizzando le proprie credenziali dell'account Google, e quindi confermare il collegamento tra i due account.
Caricare un video su YouTube
Una delle funzionalità più interessanti è la possibilità di caricare i propri video sul portale. Le modalità per effettuare questa operazione sono due:
- Caricamento diretto, nel caso in cui il file video da caricare sia presente sul proprio host;
- Caricamento via browser, nel caso in cui il file venga caricato direttamente dal navigatore.
Caricamento diretto
Proponiamo prima un esempio di caricamento diretto: questa tecnica prevede che il file video sia già presente sul proprio host, quindi in sostanza questo approccio va utilizzato quando si desidera che il video venga ospitato sia su Youtube che sul proprio spazio web.
//Inclusione del file creato in precedenza (vedi pagina 1 di questo articolo)
require_once 'youtube_setup.php';
// Creo un oggetto VideoEntry
$myVideoEntry = new Zend_Gdata_YouTube_VideoEntry();
// Creo un oggetto MediaFileSource
$filesource = $youtube->newMediaFileSource('esempio_upload.avi');
$filesource->setContentType('video/avi');
// Imposto lo "slug header"
$filesource->setSlug('esempio_upload.avi');
// Aggiungo la sorgente al VideoEntry
$myVideoEntry->setMediaSource($filesource);
$myVideoEntry->setVideoTitle('Esempio di upload');
$myVideoEntry->setVideoDescription('Un upload di esempio effettuato con la Youtube API via PHP');
// Categoria (deve essere una categoria valida)
$myVideoEntry->setVideoCategory('Howto');
// Tags: una lista di parole chiave separate da virgola
$myVideoEntry->SetVideoTags('upload, esempio, html.it');
// Developer tags (opzionale)
//$myVideoEntry->setVideoDeveloperTags(array('mydevtag', 'anotherdevtag'));
// URL di upload
$uploadUrl = 'http://uploads.gdata.youtube.com/feeds/api/users/default/uploads';
// Caricamento
try {
$newEntry = $youtube->insertEntry($myVideoEntry, $uploadUrl, 'Zend_Gdata_YouTube_VideoEntry');
} catch (Zend_Gdata_App_HttpException $httpException) {
echo $httpException->getRawResponseBody();
} catch (Zend_Gdata_App_Exception $e) {
echo $e->getMessage();
}Si parte creando un oggetto VideoEntry inizialmente vuoto, ed un oggetto MediaFileSource che rappresenta la sorgente del nostro video, ossia il file, di cui dovremo specificare il percorso ed il tipo MIME. I formati video accettati sono numerosi, e tra questi troviamo: AVI, MPEG, MOV, WMV, FLV, OGG e 3GP. Il codice di esempio associa anche uno "slug header" al file sorgente, il che fa parte del protocollo Atom usato da diversi web service offerti da Google (e non solo): si tratta di una sorta di titolo breve del documento che stiamo caricando.
Una volta associato il file sorgente all'oggetto VideoEntry, si procede specificando alcune informazioni sul video, quali il titolo, una descrizione, le eventuali etichette (tag) da associare al video stesso, e una categoria. La categoria specificata deve essere una delle categorie proposte da Youtube. Per una ricerca avanzata può essere utile aggiungere anche dei "developer tags", sulla cui trattazione rimandiamo alla documentazione ufficiale, senza approfondire in questa sede.
La parte finale del codice effettua il caricamento, in particolare la funzione insertEntry() della classe Zend_Gdata_Youtube, che richiede come primo parametro l'oggetto VideoEntry da inserire, come secondo parametro l'URL per l'upload (indicato poco prima) ed infine un terzo parametro opzionale che specifica il tipo di dato che si vuole ottenere. Da notare inoltre come vengano catturate eventuali eccezioni del tipo Zend_Gdata_App_HttpException oppure del tipo più generico Zend_Gdata_App_Exception.
Caricamento via browser
La seconda modalità di caricamento proposta consiste nel caricamento via browser. Questo prevede che sia l'utente a caricare il file direttamente su Youtube, senza passare dal nostro sito. La nostra applicazione effettua in sostanza solo una mediazione tra Youtube e i nostri navigatori. Tale mediazione avviene creando un'istanza della classe VideoEntry (che questa volta non avrà bisogno di un file sorgente) da utilizzare per ottenere un token, ossia una stringa che possa validare il dialogo tra l'utente e Youtube. Di seguito proponiamo un esempio di codice:
//Inclusione del file creato in precedenza (vedi pagina 1 di questo articolo)
require_once 'youtube_setup.php';
// Creo l'oggetto VideoEntry
$myVideoEntry = new Zend_Gdata_YouTube_VideoEntry();
$myVideoEntry->setVideoTitle('Filmato di esempio');
$myVideoEntry->setVideoDescription('Un upload di esempio, con caricamento via browser, effettuato mediante la YouTube API via PHP');
// Categoria (deve essere una categoria valida)
$myVideoEntry->setVideoCategory('Howto');
// Tags
$myVideoEntry->SetVideoTags('upload, esempio, html.it');
// Indirizzo per generare un token
$tokenHandlerUrl = 'http://gdata.youtube.com/action/GetUploadToken';
// Genero il token associato alla VideoEntry
$tokenArray = $youtube->getFormUploadToken($myVideoEntry, $tokenHandlerUrl);
$tokenValue = $tokenArray['token'];
$postUrl = $tokenArray['url'];
// Indirizzo di rindirizzamento dopo aver caricato il video
$nextUrl = 'http://mio-indirizzo.html.it/youtube_upload';
// Costruisco il form
$form = '<form action="'. $postUrl .'?nexturl='. $nextUrl .
'" method="post" enctype="multipart/form-data">'.
'<input name="file" type="file"/>'.
'<input name="token" type="hidden" value="'. $tokenValue .'"/>'.
'<input value="Carica il video" type="submit" />'.
'</form>';
echo $form;Per quanto riguarda la creazione di un oggetto di tipo VideoEntry rimandiamo all'esempio di codice mostrato nella pagina precedente in quanto rimane in sostanza tutto uguale ad eccezione della mancanza di un file video sorgente.
La generazione del token viene effettuata dal metodo getFormUploadToken() della classe Zend_Gdata_Youtube, passando come parametri l'oggetto VideoEntry ed uno specifico indirizzo URL mostrato nel codice. Il risultato di questa chiamata è un array associativo (nel codice indicato con $tokenArray) che conterrà il token vero e proprio e l'indirizzo URL da utilizzare nel form successivo, che l'utente utilizzerà per caricare il proprio filmato su Youtube. Ad operazione avvenuta l'utente verrà reindirizzato verso l'indirizzo specificato nella variabie $nextUrl inclusa nel form.
Riguardo alla creazione del form da mostrare all'utente, vanno rispettate alcune indicazioni:
- Nell'action va utilizzato un URL valido generato durante la creazione del token;
- Il metodo da utilizzare è il post;
- Trattandosi di un upload di file, va incluso il corretto enctype (come da esempio);
- Per il file da caricare si utilizza un campo input di tipo file, ovviamente, e di nome file;
- Il token va incluso come campo nascosto (hidden).
Se l'upload va a buon fine, l'utente viene reindirizzato all'indirizzo specificato che assumerà una forma del tipo: http://mio-indirizzo?status=200&id=VIDEO-ID dove la variabile status è posta a 200 per confermare l'ok (il valore sarebbe 400 in caso di bad request), mentre la variabile id riporta l'identificativo del video che sarà quindi visibile all'indirizzo www.youtube.com/watch?v=VIDEO-ID.
Ultime note sul caricamento dei video, indipendentemente dal metodo utilizzato: poiché il video viene elaborato da Youtube prima di essere reso pubblico, talvolta non risulta immediatamente disponibile per il pubblico anche se il caricamento risulta andato a buon fine ed anche se esso è visibile nella propria pagina personale sul sito. Ricordiamo inoltre che in entrambi i casi, utilizzando il sistema di autenticazione qui proposto, il video risulterà caricato a nostro nome: se vogliamo che il video sia caricato tramite l'account dei nostri visitatori, si rende necessario l'utilizzo dell'altro sistema di autenticazione, accennato nel precedente articolo e descritto a fondo nella documentazione ufficiale.
Modificare i dati di un video
Le informazioni associate ad un video (titolo, descrizione, tag e via dicendo) possono essere modificate in ogni momento, agendo sulla relativa VideoEntry. L'unico accorgimento riguarda i privilegi di accesso, in quanto normalmente gli oggetti VideoEntry che otteniamo (ad esempio con la funzione getVideoEntry() già usata nel primo articolo) sono in sola lettura, anche se la richiesta avviene tramite una sessione autenticata. Ciò si risolve forzando la funzione a restituirci una VideoEntry con pieno accesso (fullEntry).
Esaminiamo la situazione ed un esempio di modifica con il seguente frammento di codice:
//Inclusione del file creato in precedenza (vedi pagina 1 di questo articolo)
require_once 'youtube_setup.php';
// Carico la VideoEntry
$videoId = 'VIDEO-ID';
$videoEntry = $youtube->getVideoEntry($videoId, null, true);
// Modifico il video
if (isset($_POST['submit'])) {
$putUrl = $videoEntry->getEditLink()->getHref();
$videoEntry->setVideoTitle($_POST['titolo']);
$videoEntry->setVideoDescription($_POST['descrizione']);
$youtube->updateEntry($videoEntry, $putUrl);
echo "Video modificato!<br />";
}
// Mostro il form
echo "Video ID: " . $videoId . "<br />";
echo '<form method="post">' .
'Titolo: <input type="text" name="titolo" value="' . $videoEntry->getVideoTitle() . '" /><br />' .
'Descrizione: <input type="text" name="descrizione" value="' . $videoEntry->getVideoDescription() . '" /><br />' .
'<input type="submit" name="submit" value="Modifica video" />' .
'</form>';La funzione getVideoEntry() richiede soltanto il primo parametro come obbligatorio, ossia l'identificativo del video. Tuttavia per i nostri scopi, il terzo parametro va impostato a true per ottenere la possibilità di scrittura (il secondo parametro non ci interessa e viene lasciato con il valore di default, ossia null).
Il codice stampa un semplice form che mostra l'ID del video (che ovviamente non può essere modificato), il titolo e la descrizione. Non essendo specificato l'attributo action, inviando il form si ricarica la stessa pagina eseguendo il blocco di codice per la modifica. In questo blocco notiamo come sia sufficiente utilizzare funzioni già viste quali setVideoTitle() o setVideoDescription(). La novità consiste nella necessità di confermare la modifica con la funzione updateEntry(), la quale richiede come parametri la VideoEntry stessa e un indirizzo URL, ottenuto con la precedente riga tramite il metodo getEditLink() della VideoEntry.
Nota: non specificando il terzo parametro di getVideoEntry(), la funzione getEditLink() non restituisce alcun valore utile, e quindi non è possibile sfruttare la funzione updateEntry().
Cancellare un video
Per completare il quadro sulla gestione dei propri video, verifichiamo ora la possibilità di cancellare un filmato. La procedura in questo caso è estremamente semplice:
//Inclusione del file creato in precedenza (vedi pagina 1 di questo articolo)
require_once 'youtube_setup.php';
// Creo la VideoEntry
$videoId = 'VIDEO-ID';
$videoEntry = $youtube->getVideoEntry($videoId, null, true);
// Cancello il video
$youtube->delete($videoEntry);
echo "Video cancellato!<br />";Anche qui l'unico accorgimento riguarda l'uso del terzo parametro di getVideoEntry() per poter aver accesso in scrittura al video. Il metodo delete() della classe Zend_Gdata_Youtube può quindi svolgere il proprio lavoro.
Altri spunti e conclusioni
Molte sarebbero le potenzialità della Youtube API ancora da analizzare, alcune dedicate ad un utilizzo di tipo community, quali ad esempio l'uso dei commenti, dei video in risposta, dei punteggi che gli utenti danno ai video, altre dedicate a migliorare l'esperienza di ricerca dell'utente. In quest'ottica, proponiamo un ultimo esempio di codice volto ad eseguire una ricerca per parola chiave:
//Nota: per le ricerche non è indispensabile un accesso autorizzato
//Inclusione del file creato in precedenza (vedi pagina 1 di questo articolo)
require_once 'youtube_setup.php';
$youtube->setMajorProtocolVersion(2);
// costruiamo l'interrogazione
$searchTerms = 'parole da cercare';
$query = $youtube->newVideoQuery();
$query->setOrderBy('viewCount');
$query->setVideoQuery($searchTerms);
// VideoFeed in risposta
$videoFeed = $youtube->getVideoFeed($query->getQueryUrl(2));Il VideoFeed così ottenuto sarà quindi la raccolta di VideoEntry inerenti alle parole chiave cercare: dall'articolo precedente è chiaro come gestire gli oggetti di tipo VideoFeed. Da notare che per compatibilità con la precedente versione dell'API, aggiungiamo anche il numero di versione (2) nelle funzioni che lo richiedono.
In conclusione, raccomandiamo di accompagnare gli esempi proposti con la lettura dell'abbondante documentazione, al fine di approfondire tutti i numerosi dettagli che riguardano la Youtube API.
