Guida per gli sviluppatori: PHP

L'API di dati di Blogger consente alle applicazioni client di visualizzare e aggiornare i contenuti di Blogger sotto forma di feed di API di dati di Google.

La tua applicazione client può utilizzare l'API di dati di Blogger per creare nuovi post del blog, modificare o eliminare post di blog esistenti ed eseguire query per i post dei blog che corrispondono a determinati criteri.

Oltre a fornire alcune informazioni sulle funzionalità dell'API di dati di Blogger, questo documento fornisce esempi di interazioni di base dell'API di dati utilizzando la libreria client delle API di dati di Google Zend. Se ti interessa saperne di più sul protocollo sottostante utilizzato dalla libreria, consulta la sezione Protocollo di questa guida per gli sviluppatori.

Contenuti

  1. Pubblico
  2. Guida introduttiva
    1. Creazione di un account Blogger
    2. Esecuzione del codice campione
    3. Usare getter magici e setter
    4. Altre risorse
  3. Autenticazione nel servizio Blogger
    1. Autenticazione OAuth
    2. Autenticazione proxy AuthSub
    3. Autenticazione nome utente/password ClientLogin
  4. Recupero di un elenco di blog
  5. Creazione di post
    1. Pubblicazione di un post del blog
    2. Creazione di una bozza di post del blog
  6. Recupero dei post
    1. Recupero di tutti i post del blog
    2. Recupero dei post utilizzando i parametri di query
  7. Aggiornare i post
  8. Eliminare i post
  9. Commenti
    1. Creare commenti
    2. Recupero dei commenti
    3. Eliminare i commenti

Pubblico

Questo documento è destinato ai programmatori che desiderano scrivere applicazioni client PHP in grado di interagire con Blogger.

In questo documento si presume che tu abbia compreso le idee generali alla base del protocollo delle API di dati di Google.

Per informazioni di riferimento sulle classi e sui metodi forniti dalla libreria client, consulta la documentazione di riferimento API della libreria client PHP. Per informazioni generali di riferimento sull'API Blogger Data, consulta la Guida di riferimento del protocollo.

Per iniziare

Per assistenza nella configurazione della libreria client, consulta la Guida introduttiva.

La libreria client Zend richiede PHP 5.1.4 o versioni successive. È disponibile nell'ambito di Zend Framework e anche come download separato. Per interagire con Blogger, utilizza la versione 1.0.0 o successiva della libreria client.

Creazione di un account Blogger

Ti consigliamo di registrare un account Blogger a scopo di test. Blogger utilizza Account Google, quindi se disponi già di un account Google, non devi fare altro.

Esecuzione del codice campione

Un client di esempio funzionante completo, contenente tutto il codice campione mostrato in questo documento, è disponibile nel repository SVN di Zend Framework. L'esempio si trova in /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. L'esempio contiene tutte le funzioni spiegate in questo documento. Può essere eseguito solo dalla riga di comando:

php Blogger.php -- --user=[email_address] --pass=[password]

Prima di eseguire questo esempio o sviluppare il tuo codice utilizzando il framework Zend, potrebbe essere necessario impostare include_path e caricare le classi appropriate. Il percorso di inclusione può essere impostato utilizzando un'impostazione php.ini o il metodo set_include_path. Questo codice richiede l'accesso alla classe Zend_Gdata principale, alla classe Zend_Gdata_Query e alla classe di autenticazione Zend_Gdata_ClientLogin.

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_Query');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');

Usare getter magici e setter

In tutta la libreria client PHP, è stato aggiunto il supporto di magic setter/getters per comodità degli sviluppatori. Queste consentono di accedere in sicurezza alle proprietà di una classe utilizzando i metodi setter/getter tradizionali o accedendo alle proprietà. Ad esempio, se $gdataObject è un'istanza di un oggetto in questa libreria, le seguenti due righe di codice hanno effetti identici:

$gdataObject->setFoo("bar");
$gdataObject->foo = "bar";

Analogamente, anche queste due righe di codice hanno effetti identici:

$baz = $gdataObject->getFoo();
$baz = $gdataObject->foo;

Analogamente, i metodi di ingegneria magica semplificano la dichiarazione di nuovi oggetti. Anziché ricordare i nomi lunghi delle classi imposti dalla convenzione di denominazione Zend, puoi creare un nuovo object chiamando newObject(); su un client di servizio Zend. Ad esempio, i due snippet seguenti dichiarano entrambi un nuovo oggetto di estensione draft. Troverai più informazioni su drafts nella sezione Creazione di un post.

// Traditional instantiation
$gdClient = new Zend_Gdata();
$draft = new Zend_Gdata_App_Extension_Draft();

// Magic factory instantiation
$gdClient = new Zend_Gdata();
$draft = $gdClient->newDraft();

I setter/getter e le fabbriche sono facoltativi, quindi usa l'approccio più adatto a te.

Altre risorse

Altre risorse per il componente API di dati di Google di Zend Framework (Zend_Gdata):

Autenticazione nel servizio Blogger

Puoi accedere a feed pubblici e privati utilizzando l'API di dati di Blogger. I feed pubblici non richiedono alcuna autenticazione, ma sono di sola lettura. Se vuoi modificare i blog, il client deve eseguire l'autenticazione prima di richiedere feed privati. Può eseguire l'autenticazione con uno dei tre approcci seguenti: autenticazione OAuth, autenticazione proxy AuthSub o autenticazione nome utente/password ClientLogin.

Per ulteriori informazioni sull'autenticazione con le API di dati di Google in generale, consulta la documentazione sull'autenticazione.

La maggior parte degli esempi nelle sezioni successive di questo documento presuppone che tu abbia un oggetto client autenticato chiamato $gdClient.

Autenticazione OAuth

Per la documentazione sull'autenticazione OAuth tramite la libreria GData PHP di Zend, consulta OAuth nelle librerie client del protocollo dei dati di Google.

Autenticazione proxy AuthSub

L'autenticazione proxy AuthSub viene utilizzata dalle applicazioni web che devono autenticare i propri utenti tramite Account Google. L'operatore del sito web e il codice client non hanno accesso al nome utente e alla password dell'utente di Blogger; il client riceve invece speciali token AuthSub che consentono al client di agire per conto di un determinato utente. Per informazioni più dettagliate, consulta la documentazione di AuthSub.

Quando un utente visita per la prima volta la tua applicazione, non è ancora stato autenticato. In questo caso, dovrai visualizzare alcune informazioni e un link che indirizzi l'utente a una pagina Google per autenticare la tua richiesta di accesso ai suoi blog. La libreria client di Zend fornisce una funzione per generare l'URL della pagina Google. Il codice riportato di seguito recupera l'URL della pagina AuthSubRequest:

function getAuthSubUrl()
{
  $next = getCurrentUrl();
  $scope = 'http://www.google.com/blogger/feeds/';
  $secure = false;
  $session = true;
  return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure, $session);
}

$authSubUrl = getAuthSubUrl();
echo '<a href=\"$authSubUrl\">login to your Google account</a>';

Il metodo getAuthSubTokenUri richiede i seguenti parametri (corrispondenti ai parametri di query utilizzati dal gestore AuthSubRequest):

avanti
L'URL della pagina a cui Google deve reindirizzare l'utente dopo l'autenticazione.
ambito
Indica che l'applicazione richiede un token per accedere ai feed di Blogger. La stringa di ambito da utilizzare è http://www.blogger.com/feeds/ (con codifica URL, ovviamente).
sicuro
Indica se il client richiede un token sicuro.
sessione
Indica se il token restituito può essere scambiato con un token (di sessione) multiuso.

L'esempio riportato sopra mostra una chiamata che non richiede un token sicuro (il valore di secure è false). L'URL della richiesta risultante potrebbe essere simile al seguente:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.php

L'utente segue il link al sito di Google ed esegue l'autenticazione sul proprio Account Google.

Dopo l'autenticazione dell'utente, il sistema AuthSub lo reindirizza all'URL specificato nel parametro di query next dell'URL AuthSubRequest. Il sistema AuthSub aggiunge un token di autenticazione a quell'URL, come valore del parametro di query token. Ad esempio:

http://www.example.com/welcome.php?token=yourAuthToken

Puoi recuperare il valore del token utilizzando $_GET['token'].

Questo valore del token rappresenta un token AuthSub monouso. In questo esempio, dato che è stato specificato $session = true, questo token può essere scambiato con un token di sessione AuthSub utilizzando il metodo Zend_Gdata_AuthSub::getAuthSubSessionToken, che chiama il servizio AuthSubSessionToken:

if(! isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
  $_SESSION['sessionToken'] =
      Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
}

Lo snippet di codice verifica innanzitutto se è già presente un token di sessione AuthSub. In caso contrario, ma nell'URL viene specificato un token monouso, lo snippet di codice passa il token monouso al metodo getAuthSubSessionToken e l'interfaccia AuthSub restituisce un token di sessione. Il codice inserisce quindi il valore del token di sessione nella variabile di sessione $_SESSION['sessionToken'].

L'applicazione può quindi utilizzare il valore del token di sessione nelle interazioni successive con Blogger. Puoi utilizzare il metodo Zend_Gdata_AuthSub::getHttpClient per ottenere un oggetto Zend_Http_Client con l'intestazione Authorization preimpostata per includere le credenziali AuthSub:

$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);

Autenticazione nome utente/password ClientLogin

Utilizza l'autenticazione ClientLogin se il client è un client autonomo e "installato" per un singolo utente (ad esempio un'applicazione desktop).

Il codice seguente utilizza il metodo Zend_Gdata_ClientLogin::getHttpClient per eseguire una richiesta al servizio ClientLogin, recuperare un token di autenticazione e creare un oggetto Zend_Http_Client con l'intestazione di autenticazione appropriata. Quindi, HttpClient restituito da questo metodo viene utilizzato per creare un oggetto di servizio Zend_Gdata.

Nota che $accountType è impostato esplicitamente su GOOGLE. Se non imposti questo parametro, gli utenti di G Suite non potranno utilizzare l'API Blogger. 

$user = 'user@example.com';
$pass = 'secretPasswd';
$service = 'blogger';

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service, null,
        Zend_Gdata_ClientLogin::DEFAULT_SOURCE, null, null,
        Zend_Gdata_ClientLogin::CLIENTLOGIN_URI, 'GOOGLE');
$gdClient = new Zend_Gdata($client);

Per ulteriori informazioni sull'autenticazione ClientLogin, incluse richieste e risposte di esempio, consulta la documentazione Autenticazione per le applicazioni installate.

Nota: utilizza lo stesso token per tutte le richieste in una data sessione; non acquisire un nuovo token per ogni richiesta di Blogger.

Nota: come descritto nella documentazione ClientLogin, la richiesta di autenticazione potrebbe non riuscire e richiedere una verifica CAPTCHA. Se vuoi che Google emetta e gestisca il test CAPTCHA, invia l'utente a https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (anziché all'URL di gestione CAPTCHA fornito nella documentazione ClientLogin).

Recupero di un elenco di blog

L'API di dati di Blogger fornisce un feed che elenca i blog per un determinato utente; tale feed è noto come "metafeed".

Il codice di esempio seguente utilizza un oggetto $gdClient autenticato per recuperare il metafeed, quindi stampa il titolo di ogni blog.

La classe Zend_Gdata_Query si occupa di creare l'URL della query. In questo caso, non è necessario svolgere alcun lavoro aggiuntivo, ma l'utilità della classe Query diventerà visibile nella sezione Recupero dei post per parametri di query di questo documento.

function printAllBlogs()
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/default/blogs');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

function printFeed($feed)
{
  $i = 0;
  foreach($feed->entries as $entry) {
    print $i ." ". $entry->title->text . "\n";
    $i++;
  }
}

Prendi nota dell'URL utilizzato dal metodo getFeed. Questo è l'URL del metafeed predefinito e restituisce un elenco di blog per l'utente attualmente autenticato. Per accedere a un feed per un altro utente, puoi inserire l'ID utente al posto di default nell'URL del metafeed. L'ID utente è la stringa di cifre alla fine dell'URL del profilo dell'utente.

Lo snippet di codice seguente mostra come estrarre un ID blog dal feed. Avrai bisogno dell'ID blog per eseguire operazioni di creazione, aggiornamento ed eliminazione su post e commenti. La variabile $index rappresenta il blog nel feed del blog dell'utente che viene utilizzato. Il campo id ha il formato tag:blogger.com,1999:user-userID.blog-blogID, quindi un split sul carattere "-" inserisce l'ID blog nell'ultimo elemento dell'array risultante.

$idText = split('-', $feed->entries[$index]->id->text);
$blogID = $idText[2];

Creazione di post

L'API di dati di Blogger ti consente di creare e pubblicare nuovi articoli di blog, nonché di creare bozze di voci.

Nota: l'impostazione di un autore personalizzato per i post non è al momento supportata. Tutti i nuovi post verranno visualizzati come se fossero stati creati dall'utente attualmente autenticato.

Pubblicare un post del blog

Puoi utilizzare la libreria client PHP per pubblicare nuovi articoli del blog.

Per prima cosa, crea un'istanza voce per rappresentare il post del blog. Dopodiché puoi impostare titolo, contenuto e altri attributi del post del blog. Infine, chiama il metodo insertEntry per inserire il post. Puoi vedere le istanze magiche di fabbrica in funzione qui con i nuovi oggetti Zend_Gdata_Entry, Zend_Gdata_App_Extension_Title e Zend_Gdata_App_Extension_Content.

function createPublishedPost($title='Hello, world!', $content='I am blogging on the internet.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();
  $entry->title = $gdClient->newTitle($title);
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  $newPostID = $idText[2];

  return $newPostID;
}

Creazione di una bozza di post del blog

Le bozze dei post vengono create come i post pubblici, ma è necessario impostare l'attributo bozza dell'oggetto voce. Puoi creare come bozza un post del blog come quello sopra aggiungendo le righe evidenziate:

function createDraftPost($title='Salutations, world!', $content='Hmm ... not quite right, must rework the title later.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();

  $entry->title = $gdClient->newTitle(trim($title));
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $control = $gdClient->newControl();
  $draft = $gdClient->newDraft('yes');
  $control->setDraft($draft);
  $entry->control = $control;

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  return $idText[2];
}

Come per l'impostazione del titolo o dei contenuti di un post, puoi creare nuovi oggetti Zend_Gdata_App_Extension_Control e Zend_Gdata_App_Extension_Draft e assegnarli all'attributo di controllo della voce.

Puoi trasformare una bozza di post del blog esistente in un post pubblicato recuperando la bozza del post, impostando l'attributo "bozza" su no e poi aggiornando il post. Parleremo del recupero e dell'aggiornamento dei post nelle prossime due sezioni.

Recupero di post in corso

Le seguenti sezioni descrivono come recuperare un elenco di post del blog, con e senza parametri di query.

Puoi eseguire query su un feed pubblico di Blogger senza autenticazione. Pertanto, non devi impostare le credenziali o eseguire l'autenticazione AuthSub prima di recuperare i post da un blog pubblico.

Recupero di tutti i post del blog

Per recuperare i post dell'utente, richiama lo stesso metodo getFeed utilizzato per recuperare il metafeed del blog, ma questa volta invia l'URL del feed del post del blog:

function printAllPosts($gdClient, $blogID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Recupero dei post utilizzando i parametri di query

L'API di dati di Blogger consente di richiedere un insieme di voci che corrispondono a criteri specifici, come la richiesta di post di blog pubblicati o aggiornati in un determinato intervallo di date. Per farlo, puoi creare un oggetto query e passarlo al metodo getFeed.

Ad esempio, per inviare una query relativa a un intervallo di date, imposta i parametri published-min e published-max dell'oggetto query. Il seguente snippet di codice stampa il titolo e i contenuti di ogni post del blog pubblicato tra l'ora di inizio e quella di fine specificate:

function printPostsInDateRange($gdClient, $blogID, $startDate='2007-04-01', $endDate='2007-04-25')
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $query->setParam('published-min', $startDate);
  $query->setParam('published-max', $endDate);

  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Un metodo di debug utile per la classe Zend_Gdata_Query è getQueryUrl(), che ti mostrerà l'URL codificato che è stato creato.

Nota: al momento non esistono setter magici per i parametri di query published-min e published-max. Tuttavia, puoi utilizzare setStartIndex e setMaxResults.

L'API di dati di Blogger supporta i seguenti parametri di query:

categorie
Specifica le categorie (note anche come etichette) per filtrare i risultati del feed. Ad esempio, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie restituisce voci con entrambe le etichette Fritz e Laurie.
max-results
Il numero massimo di voci da restituire.
min pubblicati, max pubblicati
I limiti relativi alle date di pubblicazione delle voci.
start-index
L'indice in base uno del primo risultato da recuperare (per il paging).

Per ulteriori informazioni sui parametri di query, consulta la guida di riferimento delle API di dati di Blogger e la guida di riferimento delle API di dati di Google.

Aggiornamento dei post

Per aggiornare un post del blog esistente, devi prima recuperare la voce da aggiornare, poi modificarla e infine inviarla a Blogger utilizzando il metodo save. Il seguente snippet di codice modifica il titolo e il contenuto di una voce di blog, a condizione che tu abbia già recuperato la voce dal server.

public function updatePost($postID, $updatedTitle='Hello, World?',
                           $updatedContent='UPDATE: Still blogging',
                           $isDraft=False)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID);
  $postToUpdate = $dClient->getEntry($query);
  $postToUpdate->title->text = $this->gdClient->newTitle($updatedTitle);
  $postToUpdate->content->text = $this->gdClient->newContent($updatedContent);

  if ($isDraft) {
    $draft = $gdClient->newDraft('yes');
  } else {
    $draft = $gdClient->newDraft('no');
  }

  $control = $gdClient->newControl();
  $control->setDraft($draft);
  $postToUpdate->control = $control;

  $updatedPost = $postToUpdate->save();
  return $updatedPost;
}

Nota: la modifica dei dati dell'autore associati ai post non è attualmente supportata.

Eliminazione dei post

Per eliminare un post, passa l'URL di modifica del post al metodo delete nell'oggetto $gdClient, in questo modo:

public function deletePost($gdClient, $blogID, $postID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID;
  $gdClient->delete($uri);
}

Commenti

L'API di dati di Blogger consente di creare, recuperare ed eliminare i commenti. L'aggiornamento dei commenti non è supportato (né è disponibile nell'interfaccia web).

Creazione di commenti in corso...

Per pubblicare un commento, crea un oggetto voce e inseriscilo come segue:

function createComment($gdClient, $blogID, $postID, $commentText)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default';

  $newComment = $gdClient->newEntry();
  $newComment->content = $gdClient->newContent($commentText);
  $newComment->content->setType('text');
  $createdComment = $gdClient->insertEntry($newComment, $uri);

  $editLink = split('/', $createdComment->getEditLink()->href);
  $newCommentID = $editLink[8];

  return $newCommentID; 
}

Nota: al momento puoi pubblicare commenti solo in un blog di proprietà dell'utente autenticato.

Nota: al momento l'impostazione di un autore personalizzato per i commenti non è supportata. Tutti i nuovi commenti appariranno come se fossero stati creati dall'utente attualmente autenticato.

Recupero dei commenti in corso...

Puoi recuperare i commenti di un determinato post dall'URL del feed dei commenti del post:

public function printPostComments($gdClient, $blogID, $postID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default');
  $feed = $gdClient->getFeed($query);
  $printFeed($feed);
}

Oppure puoi recuperare i commenti di tutti i post utilizzando l'URL del feed dei commenti del blog:

http://www.blogger.com/feeds/blogID/comments/default

Eliminazione dei commenti in corso...

Per eliminare un commento, passa l'URL di modifica del commento al metodo delete sull'oggetto $gdClient in questo modo:

public function deleteComment($gdClient, $blogID, $postID, $commentID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default/' . $commentID;
  $gdClient->delete($uri);
}

Torna all'inizio