Ce document explique comment utiliser la bibliothèque cliente Java pour envoyer des requêtes de l'API Google Data ("GData") et interpréter les réponses renvoyées.
Google fournit un ensemble de bibliothèques clientes, dans différents langages de programmation, pour interagir avec des services dotés d'API de données. Ces bibliothèques vous permettent de créer des requêtes GData, de les envoyer à un service et de recevoir des réponses.
Ce document fournit des informations générales sur l'utilisation de la bibliothèque cliente Java, ainsi qu'un ensemble d'exemples d'utilisations courantes.
Pour utiliser cette bibliothèque cliente, vous devez exécuter Java 1.5.
Téléchargez la bibliothèque cliente Java.
Les exemples présentés dans ce guide font référence à l'API Google Calendar, mais ne constituent pas des guides d'utilisation précis ni à jour. Pour en savoir plus sur l'utilisation de la bibliothèque cliente Java avec l'API Data d'un service spécifique, consultez la documentation spécifique du service. Par exemple, si vous travaillez avec Agenda, consultez le guide du développeur de l'API Calendar Data.
Sommaire
Audience
Ce document est destiné aux programmeurs Java qui souhaitent écrire des applications clientes capables d'interagir avec les services GData.
Dans ce document, nous partons du principe que vous comprenez les principes généraux du protocole Google Data APIs. Nous supposons également que vous savez programmer en Java.
Pour en savoir plus 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 Java (au format Javadoc).
Ce document est conçu pour être lu dans l'ordre. Chaque exemple s'appuie sur des exemples précédents.
Présentation du modèle de données
La bibliothèque cliente Java utilise un ensemble de classes pour représenter les éléments utilisés par les API Google Data. Par exemple, il existe une classe de flux qui correspond à l'élément <atom:feed>. Elle possède des méthodes permettant de créer une entrée, d'obtenir et de définir les valeurs de divers sous-éléments, etc. Il existe également une classe Entry, qui correspond à l'élément <atom:entry>. Les éléments définis dans les API Google Data ne disposent pas tous de leur propre classe. Pour en savoir plus, consultez la documentation de référence.
La bibliothèque peut analyser automatiquement le contenu Atom et placer les valeurs des éléments Atom dans des objets appropriés. Par exemple, la méthode getFeed obtient un flux, l'analyse et renvoie un objet "Feed" avec les valeurs obtenues.
Pour envoyer un flux ou une entrée à un service, vous devez créer un objet Feed ou Entry, puis appeler une méthode de bibliothèque (telle que la méthode insert) pour traduire automatiquement l'objet en XML et l'envoyer.
Si vous le souhaitez, vous pouvez analyser et/ou générer le code XML vous-même. La méthode la plus simple consiste à utiliser une bibliothèque tierce appropriée telle que Rome.
Tout comme la syntaxe XML de l'API Google Data, le modèle d'objet correspondant est extensible. Par exemple, la bibliothèque cliente fournit des classes correspondant aux éléments définis dans l'espace de noms Google Data.
Tutoriel et exemples
Les exemples suivants montrent comment envoyer diverses requêtes API de données à l'aide de la bibliothèque cliente Java.
Pour les rendre plus concrets, ces exemples montrent comment interagir avec un service spécifique: Google Agenda. Nous allons indiquer les endroits où Agenda diffère des autres services Google afin de vous aider à adapter ces exemples pour les utiliser avec d'autres services. Pour en savoir plus sur Google Agenda, consultez la documentation sur l'API Google Calendar Data.
Créer et exécuter votre client
Pour compiler les exemples de ce document, vous devez utiliser les instructions d'importation suivantes:
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; import com.google.gdata.data.*; import com.google.gdata.data.extensions.*; import com.google.gdata.util.*; import java.net.URL;
Demander un flux
Comme indiqué dans le document API Google Calendar Data, vous pouvez demander un flux d'agenda en envoyant la requête HTTP suivante à Agenda:
GET http://www.google.com/calendar/feeds/userID/private/full
Bien entendu, vous devez remplacer userID par l'adresse e-mail de l'utilisateur. Pour en savoir plus, consultez le document Agenda. À la place, vous pouvez utiliser l'URL par défaut spéciale pour interagir avec Agenda (comme décrit dans le document Agenda), mais dans ce document, nous utiliserons l'URL de flux complet privé, qui contient l'ID utilisateur.
Vous devez également fournir une authentification appropriée. Les principales différences entre cet exemple et le premier exemple du document Google Agenda sont que (1) cet exemple inclut une authentification et (2) cet exemple utilise la classe GoogleService plus générale que la classe CalendarService spécifique à Agenda.
Notez que le système d'authentification que nous utilisons ici (connu sous le nom d'"Authentification Google pour les applications installées") ne convient qu'aux applications clientes installées, telles que les clients de bureau, et non aux applications Web. Pour en savoir plus sur l'authentification, consultez la documentation sur l'authentification des comptes Google.
Pour demander un flux d'agenda à l'aide de la bibliothèque cliente Java, saisissez le code suivant pour un utilisateur dont l'adresse e-mail est "liz@gmail.com" et le mot de passe "mypassword".
// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");
// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());
// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);
La classe GoogleService représente une connexion client (avec authentification) à un service GData. Pour envoyer une requête à un service à l'aide de la bibliothèque cliente, procédez comme suit:
- Obtenez ou créez l'URL appropriée.
- Si vous envoyez des données à un service (par exemple, si vous insérez une nouvelle entrée), transformez les données brutes en objets à l'aide des classes de la bibliothèque cliente. (Cette étape ne s'applique pas si vous demandez simplement un flux, comme nous le faisons dans cet exemple.)
- Créez une instance
GoogleServiceen définissant le nom du service (par exemple,"cl"pour Agenda) et le nom de votre application (au formatcompanyName-applicationName-versionID). - Définissez les identifiants appropriés.
- Indiquez à la bibliothèque cliente quelles extensions le flux utilisera pour lui permettre d'analyser correctement les flux renvoyés.
- Appelez une méthode pour envoyer la requête et recevoir les résultats.
La méthode setUserCredentials spécifie l'ID et le mot de passe de l'utilisateur au nom duquel votre client envoie la requête. Les exemples de ce document utilisent le système d'authentification "Authentication for Installed Applications" (Authentification pour les applications installées). Pour en savoir plus sur les systèmes d'authentification, consultez la documentation sur l'authentification des comptes Google.
Après avoir défini les identifiants, indiquez les extensions que le flux utilisera en appelant la méthode declareExtensions. Ici, nous partons du principe que le flux est un flux d'événements et qu'il utilise donc les extensions définies par le genre "Event".
Pour demander un flux entier, appelez la méthode getFeed, qui récupère une URL et renvoie l'intégralité du flux qui se trouve à cette URL. Nous vous expliquerons ultérieurement comment envoyer des requêtes plus spécifiques dans ce document.
Comme les autres méthodes de la classe GoogleService, getFeed gère l'authentification et les redirections si nécessaire.
Insérer un nouvel élément
Pour créer un événement d'agenda, vous pouvez utiliser le code suivant:
URL postUrl =
new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();
myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));
Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);
DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);
// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);
Après avoir défini l'URL, nous créons un objet EventEntry. EventEntry est dérivé de la classe de base abstraite BaseEntry, qui est également la classe parente de la classe Entry, qui représente un élément <atom:entry>.
La classe EventEntry représente un genre d'événement. Pour en savoir plus, consultez le document Kinds. Pour les services autres qu'Agenda, vous pouvez attribuer l'entrée renvoyée à un objet Entry plutôt qu'à un objet EventEntry.
Le titre de l'entrée est un TextConstruct, une classe qui contient du texte sous différentes formes (texte brut, HTML ou XHTML). Le contenu de l'entrée est représenté par un objet Content, une classe pouvant contenir du texte brut ou d'autres formes de contenu, y compris des données XML et binaires. (mais la méthode setContent peut également accepter un TextConstruct).
Chaque auteur est représenté par un nom, un URI et une adresse e-mail. (Dans cet exemple, nous ignorons l'URI.) Pour ajouter un auteur à une entrée, appelez la méthode getAuthors().add correspondante.
Nous utilisons le même objet GoogleService que celui créé dans l'exemple précédent. Dans ce cas, la méthode d'appel est insert, qui envoie un élément à l'URL d'insertion spécifiée.
Le service renvoie l'entrée nouvellement créée, qui peut contenir des éléments supplémentaires générés par le serveur, tels qu'une URL de modification pour l'entrée.
Les codes d'état HTTP sont renvoyés comme des exceptions.
Le code ci-dessus équivaut à envoyer POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (avec l'authentification appropriée) et à fournir une entrée sous la forme d'un genre d'événement.
Demander une entrée spécifique
Le code suivant vous permet de demander l'entrée spécifique que vous avez insérée dans l'exemple précédent.
Dans le contexte de cette série d'exemples, il n'est pas nécessaire de récupérer cette entrée, car Agenda a déjà renvoyé l'entrée insérée. Toutefois, la même technique peut être appliquée chaque fois que vous connaissez l'URI d'une entrée.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
L'entrée insérée possède une méthode, getSelfLink, qui renvoie un objet Link qui inclut l'URL de l'entrée. La classe Link possède une méthode getHref qui renvoie l'URL en tant que String, à partir de laquelle nous pouvons créer un objet URL.
Il suffit ensuite d'appeler la méthode getEntry du service pour obtenir l'entrée.
Notez que nous donnons EventEntry.class en tant que paramètre à getEntry, ce qui indique que nous attendons spécifiquement que le service renvoie un événement plutôt qu'une simple entrée. Pour les services autres qu'Agenda, il vous suffit de transmettre Entry.class.
Le code ci-dessus équivaut à envoyer GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID à Agenda, avec une authentification appropriée.
Rechercher des entrées
Pour extraire la première correspondance d'une recherche en texte intégral, utilisez le code suivant:
Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}
Cet exemple commence par construire un objet Query, qui consiste principalement en une URL et les paramètres de requête associés. Chacun des paramètres de requête GData standards possède une méthode setter. Vous pouvez également définir des paramètres de requête personnalisés pour un service particulier à l'aide de la méthode addCustomParameter.
Après avoir construit le Query, nous le transmettons à la méthode query du service, qui renvoie un flux contenant les résultats de la requête. Une autre approche consiste à créer une URL vous-même (en ajoutant des paramètres de requête à l'URL du flux), puis à appeler la méthode getFeed. Toutefois, la méthode query fournit une couche d'abstraction utile afin que vous n'ayez pas à créer l'URL vous-même.
La méthode getEntries du flux renvoie la liste des entrées du flux. getEntries().size renvoie le nombre d'entrées dans le flux.
Dans ce cas, si la requête a renvoyé des résultats, nous attribuons le premier résultat correspondant à un objet Entry. Ensuite, nous utilisons la méthode getTitle().getPlainText de la classe Entry pour récupérer le titre de l'entrée et le convertir en texte.
Le code ci-dessus équivaut à envoyer GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis à Agenda.
Requête par catégorie
Remarque : Google Agenda n'associe pas de libellés à des événements. Cet exemple n'est donc pas compatible avec Agenda.
Pour récupérer un flux composé de toutes les entrées correspondant à la recherche en texte intégral antérieure et qui appartiennent à une catégorie particulière ou qui possèdent un libellé donné, utilisez le code suivant:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);
Bien entendu, la classe Category représente une catégorie à utiliser dans un filtre de catégorie. La classe Query.CategoryFilter peut contenir plusieurs catégories, mais dans le cas présent, nous construisons un filtre avec une seule catégorie.
Nous ajoutons ensuite ce filtre à la requête existante, qui contient toujours la chaîne de requête en texte intégral de l'exemple précédent.
Nous utilisons à nouveau la méthode query pour envoyer la requête au service.
Si Google Agenda permettait d'effectuer une recherche par catégorie, le code ci-dessus équivaudrait à envoyer GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis à Google Agenda.
Mettre à jour un élément
Pour mettre à jour un élément existant, utilisez le code suivant : Dans cet exemple, nous remplaçons le titre de l'entrée précédemment récupérée de son ancien texte ("Tennis avec Darcy") en "Réunion importante".
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Nous commençons par définir un nouveau titre pour l'entrée que nous avons récupérée précédemment. Nous obtenons ensuite l'URL de modification de l'entrée à l'aide de la méthode getEditLink. Nous appelons ensuite la méthode update du service pour envoyer l'entrée mise à jour.
Le service renvoie l'entrée mise à jour, y compris une nouvelle URL pour la nouvelle version. (Pour en savoir plus sur les versions d'entrée, consultez la section Concurrence optimiste du document de référence du protocole.)
Le code ci-dessus équivaut à peu près à l'envoi de PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID au service, avec la nouvelle entrée (au format Atom) pour remplacer l'entrée d'origine.
Suppression d'un élément
Pour supprimer l'entrée mise à jour, utilisez le code suivant:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
L'URL à supprimer est la même que l'URL de modification. Cet exemple est donc très semblable à celui de la précédente, si ce n'est bien sûr que nous appelons la méthode delete au lieu de update.
Le code ci-dessus équivaut à peu près à l'envoi de DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID au service.
Reference
Pour en savoir plus 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 Java (au format Javadoc).