Utiliser la bibliothèque cliente Java

Ce document explique comment utiliser la bibliothèque cliente Java pour envoyer des requêtes aux 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 les services disposant 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 de ce guide font référence à l'API Google Agenda, mais ce guide n'est pas une source d'informations précise ni à jour sur l'utilisation de l'API Agenda. Pour savoir comment utiliser la bibliothèque cliente Java avec l'API Data d'un service spécifique, consultez la documentation de ce service. Par exemple, si vous utilisez Agenda, consultez le Guide du développeur pour l'API Calendar Data.

Sommaire

  1. Audience
  2. Présentation du modèle de données
  3. Tutoriel et exemples
    1. Créer et exécuter votre client
    2. Demander un flux
    3. Insérer un élément
    4. Demander une entrée spécifique
    5. Rechercher des entrées
    6. Interroger par catégorie
    7. Mettre à jour un élément
    8. Supprimer un élément
  4. Référence

Audience

Ce document est destiné aux programmeurs Java qui souhaitent écrire des applications clientes pouvant interagir avec les services GData.

Ce document part du principe que vous comprenez les idées générales du protocole des API Google Data. Nous supposons également que vous savez comment programmer en Java.

Pour obtenir des informations de référence 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, car chaque exemple s'appuie sur les 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 Feed, qui correspond à l'élément <atom:feed>. Elle comporte des méthodes permettant de créer une entrée, d'obtenir et de définir les valeurs de différents sous-éléments, etc. Il existe également une classe "Entry" (Entrée), qui correspond à l'élément <atom:entry>. Tous les éléments définis dans les API Google Data ne possèdent pas 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 vous-même du code XML. Le moyen le plus simple d'y parvenir est d'utiliser une bibliothèque tierce appropriée, telle que Rome.

Tout comme la syntaxe XML des API Google Data est extensible, le modèle d'objet correspondant l'est également. 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 différentes requêtes d'API Data à 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 vous indiquerons les différences entre Agenda et les autres services Google pour vous aider à adapter ces exemples à d'autres services. Pour en savoir plus sur Agenda, consultez la documentation de l'API Google Agenda 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 décrit dans le document API Google Calendar Data, vous pouvez demander un flux Agenda en envoyant la requête HTTP suivante à Agenda :

GET http://www.google.com/calendar/feeds/userID/private/full

Bien sûr, vous devez remplacer userID par l'adresse e-mail de l'utilisateur. Pour en savoir plus, consultez la documentation Agenda. Vous pouvez utiliser l'URL spéciale par défaut pour interagir avec Agenda (comme décrit dans le document Agenda), mais dans ce document, nous utiliserons l'URL complète du flux 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 Agenda sont les suivantes : (1) cet exemple inclut l'authentification et (2) cet exemple utilise la classe GoogleService plus générale plutôt que la classe CalendarService spécifique à Agenda.

Notez que le système d'authentification que nous utilisons ici (appelé "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 avec un compte Google.

Pour demander un flux d'agenda à l'aide de la bibliothèque cliente Java, pour un utilisateur dont l'adresse e-mail est "liz@gmail.com" et le mot de passe "mypassword", utilisez le code suivant :

// 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. La procédure générale pour envoyer une requête à un service à l'aide de la bibliothèque cliente comprend les étapes suivantes :

  1. Obtenez ou créez l'URL appropriée.
  2. 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 dans cet exemple.)
  3. Créez une instance GoogleService, en définissant le nom du service (par exemple, "cl" pour Calendar) et le nom de votre application (sous la forme companyName-applicationName-versionID).
  4. Définissez les identifiants appropriés.
  5. Indiquez à la bibliothèque cliente les extensions que le flux utilisera, afin qu'elle puisse analyser correctement les flux renvoyés.
  6. 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 "Authentification pour les applications installées". Pour en savoir plus sur les systèmes d'authentification, consultez la documentation sur l'authentification avec un compte Google.

Après avoir défini les identifiants, vous indiquez les extensions que le flux utilisera en appelant la méthode declareExtensions. Dans ce cas, nous indiquons que le flux est un flux d'événements et qu'il utilisera donc les extensions définies par le type d'événement.

Pour demander un flux entier, vous appelez la méthode getFeed, qui prend une URL et renvoie l'intégralité du flux trouvé à cette URL. Nous vous montrerons comment envoyer des requêtes plus spécifiques plus loin 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 construisons 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 type d'événement. Pour en savoir plus, consultez le document sur les types. 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 qui peut 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 omettons l'URI.) Pour ajouter un auteur à une entrée, appelez la méthode getAuthors().add de l'entrée.

Nous utilisons le même objet GoogleService que celui créé dans l'exemple précédent. Dans ce cas, la méthode à appeler 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 en tant qu'exceptions.

Le code ci-dessus équivaut à l'envoi de POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (avec une authentification appropriée) et à la fourniture d'une entrée sous la forme d'un type 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 vraiment nécessaire de récupérer cette entrée, car l'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 comporte une méthode, getSelfLink, qui renvoie un objet Link incluant l'URL de l'entrée. La classe Link possède une méthode getHref qui renvoie l'URL sous la forme d'un String, à partir duquel nous pouvons créer un objet URL.

Il ne nous reste plus qu'à appeler la méthode getEntry du service pour obtenir l'entrée.

Notez que nous fournissons EventEntry.class en tant que paramètre à getEntry, ce qui indique que nous attendons spécifiquement du service qu'il renvoie un événement plutôt qu'une simple entrée. Pour les services autres qu'Agenda, vous pouvez simplement transmettre Entry.class.

Le code ci-dessus équivaut à l'envoi de GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID à l'agenda, avec une authentification appropriée.

Rechercher des entrées

Pour récupérer 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 la construction d'un objet Query, qui se compose principalement d'une URL et des 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 spécifique à l'aide de la méthode addCustomParameter.

Après avoir construit l'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 consisterait à créer vous-même une URL (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 pour que vous n'ayez pas à créer l'URL vous-même.

La méthode getEntries du flux renvoie une liste des entrées du flux, tandis que getEntries().size renvoie le nombre d'entrées du flux.

Dans ce cas, si la requête a renvoyé des résultats, nous attribuons le premier résultat correspondant à un objet Entry. Nous utilisons ensuite 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 à l'envoi de GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis à Agenda.

Interroger par catégorie

Remarque : Google Agenda n'associe pas de libellés aux événements. Cet exemple ne fonctionne donc pas avec Agenda.

Pour récupérer un flux composé de toutes les entrées qui correspondent à la recherche en texte intégral précédente et qui appartiennent à une catégorie particulière ou qui ont un libellé particulier, 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);

La classe Category représente bien sûr une catégorie à utiliser dans un filtre de catégorie. La classe Query.CategoryFilter peut contenir plusieurs catégories, mais dans ce cas, 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 Agenda autorisait la recherche par catégorie, le code ci-dessus équivaudrait à l'envoi de GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis à Agenda.

Mettre à jour un élément

Pour mettre à jour un élément existant, utilisez le code suivant. Dans cet exemple, nous modifions le titre de l'entrée précédemment récupérée, qui était "Tennis avec Darcy", pour le remplacer par "Réunion importante".

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

Nous définissons d'abord 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 de cette entrée. (Pour en savoir plus sur les versions d'entrée, consultez la section Simultanéité 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, ainsi qu'à la nouvelle entrée (au format Atom) pour remplacer l'entrée d'origine.

Supprimer un élément

Pour supprimer l'entrée modifiée, utilisez le code suivant :

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

L'URL à utiliser pour la suppression est la même que l'URL de modification. Cet exemple est donc très semblable au précédent, sauf 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.

Référence

Pour obtenir des informations de référence 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).

Haut de page