API Blogger: premiers pas

Ce document explique comment commencer à utiliser l'API Blogger.

Avant de commencer

Obtenir un compte Google

Assurez-vous d'avoir configuré un compte Google. Nous vous recommandons d'utiliser un compte Google distinct à des fins de développement et de test pour vous protéger contre toute perte de données accidentelle. Si vous disposez déjà d'un compte de test, vous n'avez rien d'autre à faire. Vous pouvez accéder à l'interface utilisateur Blogger pour configurer, modifier ou afficher vos données de test.

Familiarisez-vous avec Blogger

Si vous ne connaissez pas les concepts de Blogger, lisez ce document et testez l'interface utilisateur avant de commencer à coder. Dans ce document, nous partons du principe que vous connaissez Blogger, les concepts de programmation Web et les formats de données Web.

En savoir plus sur l'autorisation des requêtes et l'identification de votre application

Lorsque votre application demande des données privées, la requête doit être autorisée par un utilisateur authentifié qui a accès à ces données.

Lorsque votre application demande des données publiques, la requête n'a pas besoin d'être autorisée, mais elle doit être accompagnée d'un identifiant, comme une clé API.

Pour savoir comment autoriser les requêtes et utiliser les clés API, consultez Autoriser les requêtes et identifier votre application dans le document "Utiliser l'API".

Contexte de l'API Blogger

Concepts Blogger

Blogger repose sur cinq concepts de base :

  • Blogs : concept racine de l'API. Un blog comporte des articles et des pages. Il s'agit du conteneur des méta-informations du blog, comme son nom et sa description.
  • Posts : un article de blog est un élément publiable créé par l'auteur du blog. Ces informations sont censées être d'actualité et refléter ce que les auteurs souhaitent publier au monde entier. Il est entendu qu'avec le temps, le contenu des articles de blog vieillit et devient moins pertinent.
  • Commentaires : les commentaires sont l'endroit où les personnes autres que l'auteur du post de blog réagissent à ce qu'il a écrit. Des briques aux bouquets.
  • Pages : une page est un espace dédié au contenu statique, comme des informations biographiques ou les moyens de contacter l'utilisateur. Il s'agit généralement d'informations intemporelles qui ne changent pas très souvent.
  • Utilisateurs : un utilisateur est une personne qui interagit avec Blogger, qu'elle agisse en tant qu'auteur, administrateur ou simple lecteur. Les lecteurs des blogs publics peuvent être anonymes, mais ceux des blogs privés doivent être identifiés par Blogger.

Modèle de données de l'API Blogger

Une ressource est une entité de données individuelle disposant d'un identifiant unique. L'API JSON Blogger fonctionne sur cinq types de ressources :

  • Ressource Blogs : représente un blog.
  • Ressource "Posts" : représente un post. Chaque ressource "Posts" est un enfant d'une ressource "Blogs".
  • Ressource "comments" : représente un commentaire sur un post spécifique. Chaque ressource "comments" est un enfant d'une ressource "posts".
  • Ressource "Pages" : représente une page statique. Chaque ressource "Pages" est un enfant d'une ressource "Blogs".
  • Ressource "Users" : représente un utilisateur non anonyme. Il permet d'identifier l'auteur d'une page, d'un post ou d'un commentaire.
La ressource "blogs" comporte deux types de ressources enfants : les pages et les posts. Une ressource "posts" peut avoir des ressources enfants "comments".
Présentation des relations entre les ressources

Le modèle de données de l'API Blogger est basé sur des groupes de ressources appelés collections :

Collection de blogs
Une collection de blogs <span="apicollection">se compose de tous les blogs auxquels un utilisateur a des droits d'accès. Vous pouvez lister les blogs par utilisateur ou récupérer un seul blog par ID.</span="apicollection">
Collection de posts
Une collection de posts se compose de toutes les ressources de posts d'une ressource de blogs spécifique.
Collecte des commentaires
Une collection de commentaires se compose de toutes les ressources de commentaires d'une ressource de posts spécifique.
Collection de pages
Une collection de pages se compose de toutes les ressources de pages d'une ressource de blogs spécifique.
Collection "Users"
Une collection d'utilisateurs se compose de toutes les ressources utilisateur sur Blogger et ne peut donc pas être listée. Un utilisateur peut récupérer sa propre ressource "users" (mais pas celle d'un autre utilisateur) par ID ou à l'aide de l'identifiant self.

Opérations de l'API Blogger

Vous pouvez appeler différentes méthodes sur les collections et les ressources de l'API Blogger, comme décrit dans le tableau suivant.

Opération Description Mappages HTTP REST
liste Répertorie toutes les ressources d'une collection. GET sur un URI de collection.
get Obtient une ressource spécifique. GET sur un URI de ressource.
getByUrl Récupère une ressource en la recherchant par URL. GET avec l'URL transmise en tant que paramètre.
getByPath Récupère une ressource en la recherchant par son chemin d'accès. GET avec le chemin d'accès transmis en tant que paramètre.
listByUser Liste les ressources appartenant à un utilisateur. GET sur une collection appartenant à un utilisateur.
search Recherchez des ressources en fonction d'un paramètre de requête. GET sur une URL de recherche, avec la requête transmise en tant que paramètre.
insérer Créez une ressource dans une collection. POST sur un URI de collection.
supprimer Supprime une ressource. DELETE sur un URI de ressource.
patch Mettez à jour une ressource à l'aide de la sémantique Patch. PATCH sur un URI de ressource.
update Mettez à jour une ressource. PUT sur un URI de ressource.

Le tableau ci-dessous indique les méthodes compatibles avec chaque type de ressource. Toutes les opérations list et get sur les blogs privés nécessitent une authentification.

Type de ressource
Méthodes acceptées
list get getByUrl getByPath listByUser search insert delete patch update
Blogs non oui oui non oui non non non non non
Posts oui oui non oui non oui oui oui oui oui
Commentaires oui oui non non non non non non non non
Pages oui oui non non non non non non non non
Utilisateurs non oui non non non non non non non non

Styles d'appel

Il existe plusieurs façons d'appeler l'API :

REST

REST est un style d'architecture logicielle qui permet de demander et modifier des données de manière pratique et cohérente.

Le terme REST est l'acronyme de REpresentational State Transfer. Dans le contexte des API Google, il désigne l'architecture utilisant des verbes HTTP pour récupérer et modifier les représentations des données stockées par Google.

Dans un système RESTful, les ressources sont stockées dans un datastore. Un client envoie une requête pour que le serveur exécute une action spécifique (par exemple la création, l'extraction, la mise à jour ou la suppression d'une ressource), et le serveur exécute l'action et envoie une réponse, souvent sous la forme d'une représentation de la ressource spécifiée.

Dans les API RESTful de Google, le client spécifie une action à l'aide d'un verbe HTTP comme POST, GET, PUT ou DELETE. La ressource est désignée par un URI unique au format suivant :

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Étant donné que toutes les ressources d'API possèdent des URI uniques accessibles via HTTP, REST permet la mise en cache des données, et son fonctionnement est optimisé pour l'infrastructure distribuée du Web.

Les définitions de méthode figurant dans la documentation du standard HTTP 1.1 peuvent s'avérer utiles, car elles incluent les spécifications pour GET, POST, PUT, et DELETE.

REST dans l'API Blogger

Les opérations Blogger compatibles sont directement mappées aux verbes HTTP REST, comme décrit dans Opérations de l'API Blogger.

Le format spécifique des URI de l'API Blogger est le suivant :

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

L'explication complète des URI utilisés et des résultats pour chaque opération compatible avec l'API est récapitulée dans la documentation de référence de l'API Blogger.

Exemples

Répertoriez les blogs auxquels l'utilisateur authentifié a accès :

GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY

Obtenez les articles du blog code.blogger.com, dont l'ID est 3213900 :

GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY

REST à partir de JavaScript

Vous pouvez appeler l'API Blogger depuis JavaScript à l'aide du paramètre de requête callback et en fournissant une fonction de rappel. Lorsque le navigateur charge le script, la fonction de rappel est exécutée et la réponse est fournie à la fonction de rappel. Cette approche vous permet d'écrire des applications riches qui affichent des données Blogger sans nécessiter de code côté serveur.

L'exemple suivant récupère un post du blog code.blogger.com, après que vous avez remplacé YOUR-API-KEY par votre clé API.

<html>
  <head>
    <title>Blogger API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

Format des données

JSON

JSON (JavaScript Object Notation) est un format de données qui ne dépend pas d'un langage et qui fournit une représentation textuelle simple de structures de données arbitraires. Pour en savoir plus, accédez à json.org.