L'API Blogger Data permet aux applications clientes d'afficher et de mettre à jour le contenu Blogger sous la forme de flux de l'API Google Data.
Votre application cliente peut utiliser l'API Blogger Data pour créer des articles de blog, en modifier ou en supprimer des existants, et effectuer des requêtes sur les articles de blog correspondant à des critères particuliers.
En plus de fournir des informations sur les fonctionnalités de l'API Blogger Data, ce document fournit des exemples d'interactions de base avec l'API Data à l'aide de la bibliothèque cliente Python. Pour en savoir plus sur le protocole sous-jacent utilisé par la bibliothèque, consultez la section sur le protocole de ce guide du développeur.
Sommaire
Audience
Ce document s'adresse aux programmeurs qui souhaitent écrire des applications clientes Python pouvant interagir avec Blogger.
Ce document part du principe que vous comprenez les idées générales derrière le protocole des API Google Data.
Pour en savoir plus sur l'API Blogger Data, consultez le guide de référence du protocole.
Premiers pas
Pour obtenir de l'aide pour configurer la bibliothèque cliente, consultez le guide de démarrage.
La bibliothèque cliente Python nécessite Python 2.2 ou version ultérieure. Après avoir téléchargé la bibliothèque cliente, vous devez également télécharger et installer le package ElementTree.
Créer un compte Blogger
Vous pouvez vous inscrire à un compte Blogger à des fins de test. Blogger utilise des comptes Google. Si vous possédez déjà un compte Google, vous êtes prêt.
Exécuter l'exemple de code
Un exemple de client entièrement fonctionnel, contenant tous les exemples de code présentés dans ce document, est disponible dans le fichier BloggerExample.py, sous le répertoire gdata-python-client/samples/blogger/.
L'exemple de client effectue plusieurs opérations sur le blog fourni pour illustrer l'utilisation de l'API Blogger Data.
Vous pouvez exécuter l'exemple avec les arguments suivants:
python BloggerExample.py --email [email_address] --password [password]
Pour utiliser les exemples de ce document dans votre propre code, vous avez besoin des instructions import suivantes:
from gdata import service import gdata import atom
S'authentifier auprès du service Blogger
Vous pouvez accéder aux flux publics et privés à l'aide de l'API Blogger Data. Les flux publics ne nécessitent 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 à l'aide de l'une des trois approches suivantes:authentification OAuth, authentification par proxy AuthSub ou authentification nom d'utilisateur/mot de passe ClientLogin.
Pour en savoir plus sur l'authentification avec les 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'une instance GDataService authentifiée.
Authentification OAuth
Pour en savoir plus sur l'authentification OAuth à l'aide de la bibliothèque GData Python, consultez OAuth dans les bibliothèques clientes du protocole Google Data.
Authentification par proxy AuthSub
L'authentification par 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 et au mot de passe de l'utilisateur Blogger. À la place, le client obtient des jetons AuthSub spéciaux qui lui permettent d'agir au nom d'un utilisateur particulier. Pour en savoir plus, consultez la documentation AuthSub.
Lorsqu'un utilisateur accède à votre application pour la première fois, il n'est pas encore authentifié. Dans ce cas, vous devez afficher des informations et un lien redirigeant l'utilisateur vers une page Google pour authentifier votre demande d'accès à ses blogs. La bibliothèque cliente Python 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:
def GetAuthSubUrl(): next = 'http://www.example.com/welcome.pyc' scope = 'http://www.blogger.com/feeds/' secure = False session = True blogger_service = service.GDataService() return blogger_service.GenerateAuthSubURL(next, scope, secure, session); authSubUrl = GetAuthSubUrl(); print '<a href="%s">Login to your Google account</a>' % authSubUrl
La méthode GenerateAuthSubURL 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 de portée à utiliser est
http://www.blogger.com/feeds/(encodée au format URL, bien entendu). - sécurisé
- Indique si le client demande un jeton sécurisé.
- session
- Indique si le jeton renvoyé peut être échangé contre un jeton à usage multiple (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.pyc
L'utilisateur suit le lien vers le site de Google et s'authentifie avec son compte Google.
Une fois l'utilisateur authentifié, 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.pyc?token=yourAuthToken
Il existe plusieurs façons de récupérer la valeur du jeton à partir de l'URL, par exemple:
import cgi parameters = cgi.FieldStorage() authsub_token = parameters['token']
Cette valeur de jeton représente un jeton AuthSub à usage unique. Dans cet exemple, comme session = True a été spécifié, ce jeton peut être échangé contre un jeton de session AuthSub à l'aide de la méthode UpgradeToSessionToken, qui appelle le service AuthSubSessionToken:
blogger_service = service.GDataService() blogger_service.auth_token = authsub_token blogger_service.UpgradeToSessionToken()
Autrement dit, vous transmettez votre jeton à usage unique à la méthode UpgradeToSessionToken, et l'interface AuthSub renvoie un jeton de session.
Votre application peut ensuite utiliser la valeur du jeton de session dans les interactions ultérieures avec Blogger. La bibliothèque cliente envoie automatiquement le jeton avec les requêtes.
Authentification par nom d'utilisateur/mot de passe ClientLogin
Utilisez l'authentification ClientLogin si votre client est un client "installé" autonome et à un seul utilisateur (par exemple, une application de bureau). Il vous suffit d'appeler la méthode ProgrammaticLogin() sur votre instance GDataService. Toutes les interactions ultérieures avec Blogger seront authentifiées:
blogger_service = service.GDataService('user@example.com', 'secretPassword')
blogger_service.source = 'exampleCo-exampleApp-1.0'
blogger_service.service = 'blogger'
blogger_service.account_type = 'GOOGLE'
blogger_service.server = 'www.blogger.com'
blogger_service.ProgrammaticLogin()
Dans l'extrait ci-dessus, nous définissons trois propriétés sur l'instance GDataService. Le premier est le nom de notre application sous la forme companyName-applicationName-versionID. Le second est le nom du service avec lequel nous souhaitons interagir. Le troisième est l'adresse du serveur.
Notez que account_type est explicitement défini sur GOOGLE. Si vous ne définissez pas ce paramètre, les utilisateurs de G Suite ne pourront pas utiliser l'API Blogger.
Pour en savoir plus sur l'authentification ClientLogin, y compris sur les 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'obtenez 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 demander un défi CAPTCHA. Si vous souhaitez que Google émette et gère le test CAPTCHA, redirigez l'utilisateur vers https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (plutôt que vers l'URL de gestion du CAPTCHA indiquée dans la documentation ClientLogin).
Récupérer une liste de blogs
L'API Blogger Data fournit un flux qui liste les blogs d'un utilisateur donné. Ce flux est appelé "metaflux".
L'exemple de code suivant utilise une instance GDataService authentifiée pour récupérer le métaflux, puis imprime le titre de chaque blog.
def PrintUserBlogTitles(blogger_service):
query = service.Query()
query.feed = '/feeds/default/blogs'
feed = blogger_service.Get(query.ToUri())
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
Notez l'URL utilisée par la méthode Get. 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 à un flux pour un autre utilisateur, vous pouvez remplacer default par l'ID de l'utilisateur dans l'URL du métaflux. L'ID de l'utilisateur correspond à la chaîne de chiffres située à la fin de l'URL de son profil.
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 modification et de suppression sur les posts et les commentaires. L'extrait ci-dessous choisit le premier blog récupéré pour un utilisateur.
blog_id = feed.entry[0].GetSelfLink().href.split("/")[-1]
Dans l'exemple BloggerExample.py, une classe BloggerExample est créée, et l'ID du blog est défini dans le constructeur pour un accès facile par la suite. Dans la plupart des exemples suivants de ce document, blog_id est transmis en tant que variable.
Créer des posts
L'API Blogger Data vous permet de créer et de publier des articles de blog, ainsi que des brouillons d'articles.
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 Python pour publier de nouveaux articles de blog.
Commencez par créer une instance GDataEntry 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, utilisez l'instance GDataService pour insérer le post. Voici un exemple de publication d'un article de blog:
def CreatePublicPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
blogEntry = CreatePublicPost(blogger_service, blog_id,
title='I have the answer', content='Eureka! It is 42!')
Créer un brouillon d'article de blog
Les posts en brouillon sont créés de la même manière que les posts publics, mais vous devez définir l'élément d'extension draft dans l'instance GDataEntry. L'article de blog ci-dessus peut être créé en tant que brouillon en ajoutant les lignes en surbrillance:
def CreateDraftPost(blogger_service, blog_id, title, content):
entry = gdata.GDataEntry()
entry.title = atom.Title('xhtml', title)
entry.content = atom.Content(content_type='html', text=content)
control = atom.Control()
control.draft = atom.Draft(text='yes')
entry.control = control
return blogger_service.Post(entry, '/feeds/%s/posts/default' % blog_id)
draftEntry = CreateDraftPost(blogger_service, blog_id,
title='I have the question',
content='What do you get if you multiply six by nine?')
Vous pouvez transformer un brouillon d'article de blog existant en article publié en récupérant le brouillon, en définissant l'attribut "brouillon" sur no, puis en mettant à jour l'article. Nous verrons comment récupérer et mettre à jour des posts dans les deux sections suivantes.
Récupérer des posts
Les sections suivantes expliquent comment récupérer une liste d'articles de blog, avec et sans paramètres de requête.
Vous pouvez interroger un flux public Blogger sans authentification. Par conséquent, vous n'avez pas besoin de définir d'identifiants ni d'effectuer d'authentification AuthSub avant de récupérer des posts à partir d'un blog public.
Récupérer tous les articles de blog
Pour récupérer les posts de l'utilisateur, appelez la méthode GetFeed avec l'URL du flux de posts de blog:
def PrintAllPosts(blogger_service, blog_id):
feed = blogger_service.GetFeed('/feeds/' + blog_id + '/posts/default')
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
Récupérer des posts à l'aide de paramètres de requête
L'API Blogger Data vous permet de demander un ensemble d'entrées correspondant à des critères spécifiés, par exemple en demandant des articles de blog publiés ou mis à jour dans une plage de dates donnée. Pour ce faire, créez une instance Query, puis appelez la méthode Get().
Par exemple, pour envoyer une requête de plage de dates, définissez les propriétés published_min et published_min de l'instance Query.
L'extrait de code suivant affiche le titre et le contenu de chaque article de blog publié entre l'heure de début et l'heure de fin données:
def PrintPostsInDateRange(blogger_service, blog_id, start_time='2007-04-01', end_time='2007-04-25'):
query = service.Query()
query.feed = '/feeds/' + blog_id + '/posts/default'
query.published_min = start_time
query.published_max = end_time
feed = blogger_service.Get(query.ToUri())
print feed.title.text + " posts between " + start_time + " and " + end_time
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.content.text
print "\t" + entry.updated.text
print
Notez que l'objet Query est construit à l'aide de la même URL de flux de posts utilisée pour récupérer les posts.
L'API Blogger Data est compatible avec les propriétés Query suivantes:
- 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/Laurierenvoie les entrées avec les étiquettesFritzetLaurie. Pour spécifier cette requête de catégorie dans la bibliothèque cliente Python, vous pouvez utiliserquery.categories = ['Fritz','Laurie',].
- max_results
- Nombre maximal d'entrées à renvoyer.
- published_min, published_max
- Limites des dates de publication des entrées.
- start_index
- Index en base 1 du premier résultat à récupérer (pour la pagination).
- updated_min, updated_max
- Limites des dates de mise à jour des entrées. Ces paramètres de requête sont ignorés, sauf si le paramètre
orderbyest défini surupdated.
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.
Mettre à jour des posts
Pour mettre à jour un article de blog existant, vous devez d'abord récupérer l'entrée que vous souhaitez modifier, puis la modifier, puis l'envoyer à Blogger à l'aide de la méthode Put. L'extrait de code suivant modifie le titre d'un article de blog, en supposant que vous l'avez déjà récupéré sur le serveur.
def UpdatePostTitle(blogger_service, entry_to_update, new_title='The REAL answer'):
entry_to_update.title = atom.Title('xhtml', new_title)
return blogger_service.Put(entry_to_update, entry_to_update.GetEditLink().href)
Le code ci-dessus renvoie un GDataEntry contenant l'intégralité du post nouvellement mis à jour. Pour mettre à jour d'autres propriétés, il vous suffit de les définir dans l'instance GDataEntry avant d'appeler Put.
Remarque: Il n'est pas possible de modifier les données d'auteur associées aux posts.
Supprimer des posts
Pour supprimer un post, transmettez l'URL de modification du post à la méthode Delete de votre objet GDataService, comme suit:
def DeletePost(blogger_service, edit_link_href): blogger_service.Delete(edit_link_href)
Commentaires
L'API Blogger Data permet de créer, de récupérer et de supprimer des commentaires. La modification des commentaires n'est pas possible (et n'est pas disponible dans l'interface Web).
Créer des commentaires
Pour publier un commentaire, créez un objet GDataEntry et insérez-le comme suit:
def CreateComment(blogger_service, blog_id, post_id, comment_text='Mostly harmless'): feed_uri = '/feeds/' + blog_id + '/' + post_id + '/comments/default' entry = gdata.GDataEntry() entry.content = atom.Content(content_type='xhtml', text=comment_text) return blogger_service.Post(entry, feed_uri)
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 spécifique à partir de l'URL du flux de commentaires du post:
def PrintAllComments(blogger_service, blog_id, post_id):
feed_url = '/feeds/' + blog_id + '/' + post_id + '/comments/default'
feed = blogger_service.Get(feed_url)
print feed.title.text
for entry in feed.entry:
print "\t" + entry.title.text
print "\t" + entry.updated.text
print
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 de votre objet GDataService comme suit:
def DeleteComment(blogger_service, post_id, comment_id): feed_url = '/feeds/' + post_id + '/comments/default/' + comment_id blogger_service.Delete(feed_url)