Guida per gli sviluppatori: PHP

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

L'applicazione client può utilizzare l'API Blogger Data per creare nuovi post del blog, modificare o eliminare quelli esistenti e eseguire query sui post del blog che soddisfano determinati criteri.

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

Sommario

  1. Pubblico
  2. Guida introduttiva
    1. Creare un account Blogger
    2. Eseguire il codice di esempio
    3. Utilizzare getter e setter magici
    4. Altre risorse
  3. Autenticazione al servizio Blogger
    1. Autenticazione OAuth
    2. Autenticazione proxy AuthSub
    3. Autenticazione tramite nome utente/password ClientLogin
  4. Recupero di un elenco di blog
  5. Creare post
    1. Pubblicazione di un post del blog
    2. Creare 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 è rivolto ai programmatori che vogliono scrivere applicazioni client PHP in grado di interagire con Blogger.

Questo documento presuppone che tu comprenda 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 dell'API della libreria client PHP. Per informazioni di riferimento generale sull'API Blogger Data, consulta la guida di riferimento del protocollo.

Per iniziare

Per assistenza sulla 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 dialogare con Blogger, utilizza la versione 1.0.0 o successive della libreria client.

Creare un account Blogger

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

Eseguire il codice di esempio

Un client di esempio completamente funzionante, contenente tutto il codice di esempio 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 Zend Framework, potrebbe essere necessario impostare include_path e caricare le classi appropriate. Il percorso include può essere impostato utilizzando un'impostazione php.ini o il metodo set_include_path. Questo codice richiede l'accesso alla classe di base Zend_Gdata, 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');

Utilizzo di getter e setter magici

In tutta la libreria client PHP è stato aggiunto il supporto per i magic setters/getter per comodità degli sviluppatori. Questi 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 due righe di codice riportate di seguito 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 magic factory semplificano la dichiarazione di nuovi oggetti. Anziché ricordare i nomi lunghi delle classi previsti dalla convenzione di denominazione di Zend, puoi creare un nuovo object chiamando newObject(); su un client di servizio Zend. Ad esempio, i due snippet riportati di seguito dichiarano entrambi un nuovo oggetto di estensione draft. Scopri di più su drafts nella sezione sulla 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 setters/getter magici e le factory sono facoltativi, quindi utilizza l'approccio che preferisci.

Altre risorse

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

Autenticazione al servizio Blogger

Puoi accedere ai feed pubblici e privati utilizzando l'API Blogger Data. I feed pubblici non richiedono alcuna autenticazione, ma sono di sola lettura. Se vuoi modificare i blog, il tuo cliente deve autenticarsi prima di richiedere i feed privati. Può eseguire l'autenticazione utilizzando uno dei tre approcci: autenticazione OAuth, autenticazione proxy AuthSub o autenticazione di 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 dei sample nelle sezioni successive di questo documento presuppone che tu abbia un oggetto client autenticato chiamato $gdClient.

Autenticazione OAuth

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

Autenticazione proxy AuthSub

L'autenticazione proxy AuthSub viene utilizzata dalle applicazioni web che devono autenticare i propri utenti negli 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 ottiene invece token AuthSub speciali che gli consentono 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, devi mostrare alcune informazioni e un link che indirizzi l'utente a una pagina di Google per autenticare la tua richiesta di accesso ai suoi blog. La libreria client Zend fornisce una funzione per generare l'URL della pagina Google. Il codice seguente 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 accetta i seguenti parametri (corrispondenti ai parametri di query utilizzati dall'handler AuthSubRequest):

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

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

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 e si autentica nel proprio Account Google.

Dopo che l'utente ha eseguito l'autenticazione, 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, poiché è stato specificato $session = true, questo token può essere scambiato per 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 sessione AuthSub. In caso contrario, se nell'URL è 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 sessione nella variabile sessione $_SESSION['sessionToken'].

La tua applicazione potrà 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 tramite nome utente/password ClientLogin

Utilizza l'autenticazione ClientLogin se il client è un client "installato" autonomo per un solo 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, il valore HttpClient restituito da questo metodo viene utilizzato per creare un oggetto servizio Zend_Gdata.

Tieni presente che $accountType è impostato esplicitamente su GOOGLE. Se non imposti questo parametro, gli utenti di G Suite non potranno utilizzare correttamente 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 sull'autenticazione per le applicazioni installate.

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

Nota: come descritto nella documentazione di ClientLogin, la richiesta di autenticazione potrebbe non riuscire e richiedere una verifica CAPTCHA. Se vuoi che sia Google a emettere e gestire la verifica CAPTCHA, indirizza l'utente all'URL https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (anziché all'URL di gestione del CAPTCHA indicato nella documentazione di ClientLogin).

Recupero di un elenco di blog

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

Il seguente codice di esempio utilizza un oggetto $gdClient autenticato per recuperare il metafeed e stampare il titolo di ogni blog.

La classe Zend_Gdata_Query si occupa di creare l'URL query. In questo caso, non è necessario svolgere alcun lavoro aggiuntivo, ma l'utilità della classe Query diventerà evidente nella sezione Recupero dei post tramite 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. Si tratta dell'URL del metafeed predefinito; restituisce un elenco di blog per l'utente autenticato corrente. Per accedere a un feed per un utente diverso, 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 riportato di seguito mostra come estrarre un ID blog dal feed. L'ID blog è necessario per eseguire operazioni di creazione, aggiornamento ed eliminazione su post e commenti. La variabile $index rappresenta il blog nel feed del blog dell'utente in uso. Il campo id assume la forma 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];

Creare post

L'API Blogger Data consente di creare e pubblicare nuove voci del blog, nonché bozze di voci.

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

Pubblicazione di un post del blog

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

Per prima cosa, crea un'istanza di voce per rappresentare il post del blog. Poi puoi impostare il titolo, i contenuti e altri attributi del post del blog. Infine, chiama il metodo insertEntry per inserire il post. Puoi vedere le istanze della factory magica in azione 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;
}

Creare una bozza di un post del blog

I post in bozza vengono creati nello stesso modo dei post pubblici, ma devi impostare l'attributo draft dell'oggetto entry. Puoi creare un post del blog come quello riportato sopra come bozza 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];
}

In modo molto simile all'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, impostando l'attributo bozza su no e poi aggiornando il post. Il recupero e l'aggiornamento dei post verranno trattati nelle due sezioni successive.

Recupero dei post

Le sezioni seguenti 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 è necessario 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, chiama lo stesso metodo getFeed utilizzato per recuperare il metafeed dei blog, ma questa volta invia l'URL del feed dei 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 Blogger Data ti consente di richiedere un insieme di voci che corrispondono a criteri specificati, ad esempio richiedere post del blog pubblicati o aggiornati in un determinato intervallo di date. Per farlo, crea un oggetto query e passalo al metodo getFeed.

Ad esempio, per inviare una query con intervallo di date, imposta i parametri published-min e published-max dell'oggetto query. Lo snippet di codice seguente stampa il titolo e i contenuti di ogni post del blog pubblicato tra la data e l'ora di inizio e la data e l'ora 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 mostra l'URL codificato che è stato creato.

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

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

categorie
Specifica le categorie (dette anche etichette) per filtrare i risultati del feed. Ad esempio, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie restituisce voci con le etichette Fritz e Laurie.
max-results
Il numero massimo di voci da restituire.
published-min, published-max
I limiti per le date di pubblicazione delle voci.
start-index
L'indice a partire da 1 del primo risultato da recuperare (per la paginazione).

Per ulteriori informazioni sui parametri di query, consulta la Guida di riferimento dell'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 un post del blog, supponendo che tu abbia già recuperato il post 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.

Eliminare i post

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

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

Commenti

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

Creazione di commenti

Per pubblicare un commento, crea un oggetto entry 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 su un blog di proprietà dell'utente autenticato.

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

Recupero dei commenti

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);
}

In alternativa, 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

Per eliminare un commento, passa l'URL di modifica del commento al metodo delete nell'oggetto $gdClient come segue:

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

Torna all'inizio