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
Zend_Gdata_YouTube
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
developer key
Nota sull'autenticazione
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
- Caricamento via browser
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
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 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
VideoEntry
getVideoEntry()
VideoEntry
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()
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
setVideoTitle()
setVideoDescription()
updateEntry()
VideoEntry
getEditLink()
VideoEntry
Nota
getVideoEntry()
getEditLink()
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()
delete()
Zend_Gdata_Youtube
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
VideoFeed
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.
