Guide du développeur: PHP

L'API Blogger Data permet aux applications clientes d'afficher et de mettre à jour le contenu de Blogger sous la forme de flux d'API Google Data.

Votre application cliente peut utiliser l'API Blogger Data pour créer des articles de blog, modifier ou supprimer des articles de blog existants et rechercher des articles de blog correspondant à des critères particuliers.

En plus de vous familiariser avec les fonctionnalités de l'API Data de Blogger, ce document fournit des exemples d'interactions avec l'API Data de base à l'aide de la bibliothèque cliente Zend Google Data APIs. Si vous souhaitez en savoir plus sur le protocole sous-jacent utilisé par la bibliothèque, consultez la section Protocole de ce guide du développeur.

Contenus

  1. Audience
  2. Premiers pas
    1. Créer un compte Blogger
    2. Exécuter l'exemple de code
    3. Utiliser des getters et des setters magiques
    4. Autres ressources
  3. S'authentifier auprès du service Blogger
    1. Authentification OAuth
    2. Authentification du proxy AuthSub
    3. Authentification du nom d'utilisateur/mot de passe ClientLogin
  4. Récupérer une liste de blogs
  5. Créer des posts
    1. Publier un article de blog
    2. Créer un article de blog
  6. Récupérer des posts
    1. Récupérer tous les articles de blog
    2. Récupérer des posts à l'aide de paramètres de requête
  7. Modifier des posts
  8. Supprimer des posts
  9. Commentaires
    1. Créer des commentaires
    2. Récupérer des commentaires
    3. Supprimer des commentaires

Audience

Ce document est destiné aux programmeurs qui souhaitent écrire des applications clientes PHP capables d'interagir avec Blogger.

Dans ce document, nous partons du principe que vous comprenez les principes généraux du protocole Google Data APIs.

Pour plus d'informations sur les classes et les méthodes fournies par la bibliothèque cliente, consultez la documentation de référence de l'API de la bibliothèque cliente PHP. Pour obtenir des informations de référence générales sur l'API Data de Blogger, consultez le guide de référence du protocole.

Commencer

Si vous avez besoin d'aide pour configurer la bibliothèque cliente, consultez le guide de démarrage.

La bibliothèque cliente Zend nécessite PHP 5.1.4 ou une version ultérieure. Il est disponible dans le framework de Zend et peut être téléchargé séparément. Pour interagir avec Blogger, utilisez la version 1.0.0 ou ultérieure de la bibliothèque cliente.

Créer un compte Blogger

Vous pouvez créer un compte Blogger à des fins de test. Blogger utilise les comptes Google. Si vous en avez déjà un, vous n'avez rien à faire.

Exécuter l'exemple de code

Un exemple de client complet, contenant tous les exemples de code présentés dans ce document, est disponible dans le dépôt SVN du framework Zend. L'exemple se trouve à l'emplacement /framework/standard/jonction/demos/Zend/Gdata/Blogger.php. L'exemple contient toutes les fonctions expliquées dans ce document. Elle ne peut être exécutée qu'à partir de la ligne de commande:

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

Avant d'exécuter cet exemple ou de développer votre propre code à l'aide du framework Zend, vous devrez peut-être définir include_path et charger les classes appropriées. Le chemin d'inclusion peut être défini à l'aide d'un paramètre php.ini ou de la méthode set_include_path. Ce code demande l'accès à la classe principale Zend_Gdata, à la classe Zend_Gdata_Query et à la classe d'authentification 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');

Utiliser des getters et des setters magiques

Dans la bibliothèque cliente PHP, la compatibilité avec les setters/getters magiques a été ajoutée pour faciliter le travail des développeurs. Celles-ci permettent d'accéder en toute sécurité aux propriétés d'une classe à l'aide de méthodes setter/getter traditionnelles ou en accédant aux propriétés. Par exemple, si $gdataObject est une instance d'un objet de cette bibliothèque, les deux lignes de code suivantes ont des effets identiques:

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

De même, ces deux lignes de code ont également des effets identiques:

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

De même, les méthodes de fabrique de magie permettent de déclarer plus facilement de nouveaux objets. Au lieu de vous souvenir des noms de classe longs imposés par la convention d'attribution de noms Zend, vous pouvez créer un object en appelant newObject(); sur un client de service Zend. Par exemple, les deux extraits suivants déclarent un nouvel objet d'extension draft. Vous trouverez plus d'informations sur drafts dans la section Créer 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();

Les setters/getters magiques sont facultatifs. Utilisez l'approche qui vous convient le mieux.

Autres ressources

Autres ressources pour le composant des API de données Google de Zend (Zend_Gdata):

S'authentifier sur le service Blogger

Vous pouvez accéder aux flux publics et privés à l'aide de l'API Blogger Data. Les flux publics ne requièrent aucune authentification, mais ils sont en lecture seule. Si vous souhaitez modifier des blogs, votre client doit s'authentifier avant de demander des flux privés. Il peut s'authentifier selon l'une des trois approches suivantes: l'authentification OAuth, l'authentification du proxy AuthSub ou l'authentification par nom d'utilisateur/mot de passe ClientLogin.

Pour en savoir plus sur l'authentification auprès des API Google Data en général, consultez la documentation sur l'authentification.

La plupart des exemples des sections suivantes de ce document supposent que vous disposez d'un objet client authentifié appelé $gdClient.

Authentification OAuth

Pour en savoir plus sur l'authentification OAuth avec la bibliothèque GData Zend PHP, consultez OAuth dans les bibliothèques clientes du protocole Google Data.

Authentification du proxy AuthSub

L'authentification de proxy AuthSub est utilisée par les applications Web qui doivent authentifier leurs utilisateurs auprès de comptes Google. L'opérateur du site Web et le code client n'ont pas accès au nom d'utilisateur ni au mot de passe de l'utilisateur Blogger. À la place, le client obtient des jetons AuthSub spéciaux qui lui permettent d'agir pour le compte d'un utilisateur particulier. Pour en savoir plus, consultez la documentation AuthSub.

Lorsqu'un utilisateur visite votre application pour la première fois, il n'a pas encore été authentifié. Dans ce cas, vous devez afficher des informations et un lien redirigeant l'utilisateur vers une page Google afin d'authentifier votre demande d'accès à ses blogs. La bibliothèque cliente Zend fournit une fonction permettant de générer l'URL de la page Google. Le code ci-dessous récupère l'URL de la page 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>';

La méthode getAuthSubTokenUri utilise les paramètres suivants (correspondant aux paramètres de requête utilisés par le gestionnaire AuthSubRequest):

suivant
URL de la page vers laquelle Google doit rediriger l'utilisateur après l'authentification.
champ d'application
Indique que l'application demande un jeton pour accéder aux flux Blogger. La chaîne du champ d'application à utiliser est http://www.blogger.com/feeds/ (encodé en URL, évidemment).
sécurisé
Indique si le client demande un jeton sécurisé.
session
Indique si le jeton renvoyé peut être échangé contre un jeton à usages multiples (session).

L'exemple ci-dessus montre un appel qui ne demande pas de jeton sécurisé (la valeur de secure est false). L'URL de requête obtenue peut se présenter comme suit:

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'utilisateur suit le lien vers le site de Google et s'authentifie sur son compte Google.

Une fois l'authentification de l'utilisateur effectuée, le système AuthSub le redirige vers l'URL que vous avez spécifiée dans le paramètre de requête next de l'URL AuthSubRequest. Le système AuthSub ajoute un jeton d'authentification à cette URL, en tant que valeur du paramètre de requête token. Exemple :

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

Vous pouvez récupérer la valeur du jeton à l'aide de $_GET['token'].

Cette valeur de jeton représente un jeton AuthSub à usage unique. Dans cet exemple, étant donné que $session = true a été spécifié, ce jeton peut être échangé contre un jeton de session AuthSub à l'aide de la méthode Zend_Gdata_AuthSub::getAuthSubSessionToken, qui appelle le service AuthSubSessionToken:

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

L'extrait de code vérifie d'abord si un jeton de session AuthSub est déjà présent. Si ce n'est pas le cas, mais qu'un jeton à usage unique est spécifié dans l'URL, l'extrait de code transmet le jeton à usage unique à la méthode getAuthSubSessionToken, et l'interface AuthSub renvoie un jeton de session. Le code place ensuite la valeur du jeton de session dans la variable de session $_SESSION['sessionToken'].

Votre application peut ensuite utiliser la valeur du jeton de session lors des interactions ultérieures avec Blogger. Vous pouvez utiliser la méthode Zend_Gdata_AuthSub::getHttpClient pour obtenir un objet Zend_Http_Client dont l'en-tête Authorization est prédéfini pour inclure les identifiants AuthSub:

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

Authentification du nom d'utilisateur/mot de passe ClientLogin

Utilisez ClientLogin si votre client est un client autonome à installation unique (application de bureau, par exemple).

Le code suivant utilise la méthode Zend_Gdata_ClientLogin::getHttpClient pour envoyer une requête au service ClientLogin, récupérer un jeton d'authentification et créer un objet Zend_Http_Client avec l'en-tête d'authentification approprié. Ensuite, le HttpClient renvoyé par cette méthode est utilisé pour construire un objet de service Zend_Gdata.

Notez que $accountType est explicitement défini sur GOOGLE. Si ce paramètre n'est pas défini, les utilisateurs G Suite ne pourront pas utiliser 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);

Pour plus d'informations sur l'authentification ClientLogin, y compris des exemples de requêtes et de réponses, consultez la documentation Authentification pour les applications installées.

Remarque: Utilisez le même jeton pour toutes les requêtes d'une session donnée. N'acquérez pas de nouveau jeton pour chaque requête Blogger.

Remarque : Comme décrit dans la documentation ClientLogin, la requête d'authentification peut échouer et entraîner un test CAPTCHA. Si vous souhaitez que Google émette et gère le test CAPTCHA, envoyez l'utilisateur vers https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (plutôt que vers l'URL de traitement CAPTCHA fournie dans la documentation ClientLogin).

Récupérer une liste de blogs

L'API Blogger Data fournit un flux qui répertorie les blogs d'un utilisateur particulier. Ce flux est appelé "metafeed".

L'exemple de code suivant utilise un objet $gdClient authentifié pour récupérer le métaflux, puis imprime le titre de chaque blog.

La classe Zend_Gdata_Query se charge de construire l'URL de la requête. Dans ce cas, aucune tâche supplémentaire n'est requise, mais l'utilité de la classe Query apparaîtra dans la section Récupération des posts par paramètres de requête de ce document.

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

Notez l'URL utilisée par la méthode getFeed. Il s'agit de l'URL du métaflux par défaut. Elle renvoie la liste des blogs de l'utilisateur actuellement authentifié. Pour accéder au flux d'un autre utilisateur, vous pouvez remplacer l'ID de l'utilisateur par default dans l'URL du métaflux. L'ID utilisateur correspond à la chaîne de chiffres située à la fin de l'URL du profil de l'utilisateur.

L'extrait de code ci-dessous montre comment extraire un ID de blog du flux. Vous aurez besoin de l'ID du blog pour effectuer des opérations de création, de mise à jour et de suppression sur les articles et les commentaires. La variable $index représente le blog utilisé dans le flux de blog de l'utilisateur. Le champ id prend la forme tag:blogger.com,1999:user-userID.blog-blogID, par conséquent un split sur le caractère '-' place l'ID de blog dans le dernier élément du tableau obtenu.

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

Création de posts

L'API Blogger Data vous permet de créer et de publier de nouvelles entrées de blog, mais aussi de créer des brouillons d'entrées.

Remarque : Il n'est actuellement pas possible de définir un auteur personnalisé pour les posts. Tous les nouveaux posts apparaîtront comme s'ils avaient été créés par l'utilisateur actuellement authentifié.

Publier un article de blog

Vous pouvez utiliser la bibliothèque cliente PHP pour publier de nouvelles entrées de blog.

Commencez par créer une instance d'entrée pour représenter l'article de blog. Vous pouvez ensuite définir le titre, le contenu et d'autres attributs de l'article de blog. Enfin, appelez la méthode insertEntry pour insérer le post. Vous pouvez voir les instanciations de l'usine magique ici à l'œuvre avec les nouveaux objets Zend_Gdata_Entry, Zend_Gdata_App_Extension_Title et 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;
}

Créer un brouillon d'article de blog

Les brouillons sont créés de la même manière que les posts publics, mais vous devez définir l'attribut brouillon de l'objet d'entrée. Vous pouvez créer un article de blog comme celui ci-dessus en tant que brouillon en ajoutant les lignes en surbrillance:

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

Tout comme vous définissez le titre ou le contenu d'un post, vous créez des objets Zend_Gdata_App_Extension_Control et Zend_Gdata_App_Extension_Draft, puis vous les affectez à l'attribut de contrôle de l'entrée.

Vous pouvez transformer un brouillon de blog en article publié en le récupérant, en définissant l'attribut de brouillon sur no, puis en mettant à jour le post. Nous aborderons la récupération et la mise à jour des articles dans les deux sections suivantes.

Récupération des posts

Les sections suivantes expliquent comment récupérer la liste des articles de blog, avec et sans paramètres de requête.

Vous pouvez interroger un flux public Blogger sans authentification. Vous n'avez donc pas besoin de définir des identifiants ni d'effectuer une authentification AuthSub avant de récupérer des articles d'un blog public.

Récupération de tous les articles de blog

Pour récupérer les articles de l'utilisateur, appelez la même méthode getFeed que celle utilisée pour récupérer le métaflux des blogs, mais cette fois, envoyez l'URL du flux d'articles de blog:

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

Récupérer des posts à l'aide des paramètres de requête

L'API Data de Blogger vous permet de demander un ensemble d'entrées correspondant aux critères spécifiés, par exemple des articles de blog publiés ou mis à jour dans une plage de dates donnée. Pour ce faire, vous devez créer un objet de requête et le transmettre à la méthode getFeed.

Par exemple, pour envoyer une requête de plage de dates, définissez les paramètres published-min et published-max de l'objet de requête. L'extrait de code suivant imprime le titre et le contenu de chaque article de blog publié entre l'heure de début et l'heure de fin indiquées:

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

La méthode getQueryUrl() est une méthode de débogage utile pour la classe Zend_Gdata_Query. Elle indique l'URL encodée qui a été créée.

Remarque: Il n'existe actuellement aucun setter magique pour les paramètres de requête published-min et published-max. Toutefois, vous pouvez utiliser setStartIndex et setMaxResults.

L'API Blogger Data accepte les paramètres de requête suivants:

catégories
Spécifie des catégories (également appelées libellés) pour filtrer les résultats du flux. Par exemple, http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie renvoie les entrées contenant les libellés Fritz et Laurie.
résultats max
Nombre maximal d'entrées à renvoyer.
publié-min, publié-max
Limites liées aux dates de publication des entrées.
index de départ
Index de base 1 du premier résultat à récupérer (pour la pagination).

Pour en savoir plus sur les paramètres de requête, consultez le guide de référence de l'API Blogger Data et le guide de référence des API Google Data.

Mise à jour des posts...

Pour mettre à jour un article de blog existant, commencez par récupérer l'entrée que vous souhaitez mettre à jour, modifiez-la, puis envoyez-la à Blogger à l'aide de la méthode save. L'extrait de code suivant modifie le titre et le contenu d'une entrée de blog, en supposant que vous avez déjà récupéré l'entrée sur le serveur.

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

Remarque: Il n'est actuellement pas possible de modifier les données d'auteur associées aux posts.

Suppression des posts

Pour supprimer un post, transmettez l'URL de modification du post à la méthode delete sur votre objet $gdClient, comme suit:

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

Commentaires

L'API Blogger Data permet de créer, de récupérer et de supprimer des commentaires. Il n'est pas possible de mettre à jour les commentaires (ni dans l'interface Web).

Créer des commentaires

Pour publier un commentaire, créez un objet d'entrée et insérez-le comme suit:

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

Remarque : Actuellement, vous ne pouvez publier des commentaires que sur un blog appartenant à l'utilisateur authentifié.

Remarque: Il n'est actuellement pas possible de définir un auteur personnalisé pour les commentaires. Tous les nouveaux commentaires apparaîtront comme s'ils avaient été créés par l'utilisateur actuellement authentifié.

Récupération des commentaires...

Vous pouvez récupérer les commentaires d'un post donné à partir de l'URL du flux des commentaires du 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);
}

Vous pouvez également obtenir les commentaires de tous les articles à l'aide de l'URL du flux de commentaires du blog:

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

Suppression des commentaires...

Pour supprimer un commentaire, transmettez l'URL de modification du commentaire à la méthode delete sur votre objet $gdClient comme suit:

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

Haut de page