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 dati di Google.

L'applicazione client può utilizzare l'API di dati di Blogger per creare nuovi post del blog, modificare o eliminare i post del blog esistenti e fare query per post di blog che corrispondono a criteri specifici.

Oltre a fornire alcune informazioni di base sulle funzionalità dell'API di dati di Blogger, questo documento fornisce esempi di interazioni di base di API di dati utilizzando la libreria client delle API di dati di Google Zend. Se ti interessa comprendere meglio il protocollo sottostante utilizzato dalla libreria, consulta la sezione sul protocollo della guida di questo sviluppatore.

Contenuti

1. Pubblico
2. Inizia
   1. Creare un account Blogger
   2. Eseguire il codice campione
   3. Utilizzo di getter e setter magici
   4. Altre risorse
3. Autenticarsi nel servizio Blogger
   1. Autenticazione OAuth
   2. Autenticazione proxy AuthSub
   3. Autenticazione nome utente/password ClientLogin
4. Recuperare un elenco di blog
5. Creazione di post
   1. Pubblicare un post del blog
   2. Creare una bozza del post del blog
6. Recupero dei post
   1. Recupero di tutti i post del blog
   2. Recuperare i post utilizzando i parametri di ricerca
7. Aggiornamento dei post
8. Eliminare 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.

Questo documento presuppone che tu abbia compreso le idee generali alla base del protocollo API di dati di Google.

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

Per cominciare

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

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

Creazione di un account Blogger

Ti consigliamo di creare un account Blogger per scopi di test. Blogger utilizza gli Account Google pertanto, se hai già un Account Google, non devi fare altro.

Eseguire il codice campione

Un client di esempio funzionante completo, contenente tutto il codice di esempio mostrato in questo documento, è disponibile nel repository SVN Framework Zend. 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 di sviluppare il tuo codice utilizzando il ZendFramework, potresti dover impostare include_path e caricare le classi appropriate. Il percorso di inclusione può essere configurato con un'impostazione php.ini o con il metodo set_include_path. Questo codice richiede l'accesso alla classe Zend_Gdata di base, 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 di magic setter/getters per agevolare gli sviluppatori. Queste proprietà consentono di accedere alle proprietà di una classe in modo sicuro utilizzando 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 magici di fabbrica semplificano la dichiarazione di nuovi oggetti. Invece di ricordare i nomi di classe lunghi richiesti dalla convenzione di denominazione Zend, puoi creare un nuovo object chiamando newObject(); su un client di servizio Zend. Ad esempio, i seguenti due snippet dichiarano entrambi un nuovo oggetto estensione draft. Troverai maggiori 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/matrimoni e le fabbriche magiche sono facoltativi, quindi utilizza l'approccio più adatto alle tue esigenze.

Altre risorse

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

• Documentazione di riferimento
• Informazioni sulla mailing list e archivi
• Informazioni sulla versione secondaria di Zend Framework
• Istantanea istantanee per notte di Zend Framework

Autenticazione al servizio Blogger

Puoi accedere ai feed pubblici e privati utilizzando l'API dei dati di Blogger. I feed pubblici non richiedono alcuna autenticazione, ma sono di sola lettura. Se vuoi modificare i blog, il tuo cliente deve eseguire l'autenticazione prima di richiedere i feed privati. Può eseguire l'autenticazione utilizzando 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 utilizzando la libreria ZData PHP GData, consulta OAuth nelle librerie client del protocollo Google Data.

Autenticazione proxy AuthSub

L'autenticazione del proxy AuthSub viene utilizzata dalle applicazioni web che devono autenticare gli 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 invece riceve token AuthSub speciali 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, devi visualizzare alcune informazioni e un link che indirizza l'utente a una pagina Google per autenticare la richiesta di accesso ai suoi blog. La libreria client di 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 ricerca 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 dell'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 multiuso (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 autentica il proprio Account Google.

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

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

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

Questo valore token rappresenta un token AuthSub monouso. In questo esempio, poiché è stato specificato $session = true, è possibile scambiare questo token 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 controlla innanzitutto se è già presente un token della sessione AuthSub. Se non lo è, ma nell'URL è specificato un token monouso, lo snippet di codice passa il token monouso al metodo getAuthSubSessionToken e l'interfaccia AuthSub restituisce un token sessione. Il codice inserisce quindi il valore del token della sessione nella variabile $_SESSION['sessionToken'] della sessione.

L'applicazione può quindi utilizzare il valore del token della 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, "singolo" per utente singolo (come 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. Il metodo HttpClient restituito da questo metodo viene utilizzato per creare un oggetto di servizio Zend_Gdata.

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

$user = '[e-mail]';
$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 le richieste e le 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 Google emetta e gestisca la verifica 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 in corso...

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

Il seguente codice di esempio 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 query. In questo caso, non sarà necessario alcun lavoro aggiuntivo, ma l'utilità della classe Query diventerà evidente nella sezione recupero dei post in base ai parametri di ricerca 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 predefinito del metafeed, che restituisce un elenco di blog per l'utente attualmente autenticato. Per accedere a un feed per un altro utente, puoi inserire l'ID dell'utente al posto di default nell'URL del metafeed. L'ID utente è la stringa di cifre che si trova alla fine dell'URL del profilo dell'utente.

Lo snippet di codice riportato di seguito illustra 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 utilizzato. Il campo id assume la forma tag:blogger.com,1999:user-userID.blog-blogID, quindi un split sul carattere '-' posiziona l'ID del blog nell'ultimo elemento dell'array risultante.

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

Creazione di post

L'API Blogger Data consente di creare e pubblicare nuove voci di blog, nonché di creare 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.

Pubblicare un post del blog

Puoi utilizzare la libreria client PHP per pubblicare nuove voci di blog.

Per prima cosa, crea un'istanza di voce per rappresentare il post del blog. Puoi impostare il titolo, i contenuti e altri attributi del post del blog. Infine, chiama il metodo insertEntry per inserire il post. Puoi vedere qui le magari delle istanze di fabbrica 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 nello stesso modo dei post pubblici, ma devi impostare l'attributo bozza dell'oggetto voce. 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 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.

Per trasformare una bozza di post di blog esistente in un post pubblicato, recupera la bozza, imposta l'attributo bozza su no, quindi aggiorna il post. Parleremo del recupero e dell'aggiornamento dei post nelle prossime sezioni.

Recupero dei post in corso...

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

Puoi eseguire query su un feed pubblico di Blogger senza autenticazione. quindi 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 in corso...

Per recuperare i post dell'utente, chiama lo stesso metodo getFeed usato per recuperare il metafeed dei 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 mediante parametri di ricerca

L'API di dati di Blogger consente di richiedere un set di voci che corrispondono a criteri specifici, come la richiesta di post del blog pubblicati o aggiornati in un determinato intervallo di date. A questo scopo, crea un oggetto query e passalo al metodo getFeed.

Ad esempio, per inviare una query sull'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 mostra l'URL codificato che è stato creato.

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

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

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 le voci con le etichette Fritz e Laurie.

max risultati

Il numero massimo di voci da restituire.

min-pubblicato-max-pubblicato

I limiti per le date di pubblicazione delle iscrizioni.

indice-indice

L'indice in base uno del primo risultato da recuperare (per il paging).

Per ulteriori informazioni sui parametri di ricerca, consulta la Guida di riferimento API per i dati di Blogger e la Guida di riferimento per le API di dati Google.

Aggiornamento dei post in corso...

Per aggiornare un post del blog esistente, devi prima recuperare la voce che vuoi aggiornare, quindi modificarla, quindi inviarla a Blogger utilizzando il metodo save. Lo snippet di codice riportato di seguito modifica il titolo e il contenuto di una voce di blog, supponendo 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 in corso...

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 Blogger Data consente di creare, recuperare ed eliminare i commenti. L'aggiornamento dei commenti non è supportato (né è disponibile nell'interfaccia web).

Creazione di commenti

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

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

Recupero dei commenti in corso...

Puoi recuperare i commenti relativi a 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 ottenere i commenti da tutti i post utilizzando l'URL del feed dei commenti del blog:

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

Eliminazione commenti

Per eliminare un commento, passa l'URL di modifica del commento al metodo delete sul tuo 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