Guide du développeur de la bibliothèque cliente .NET

Ce document explique comment utiliser la bibliothèque cliente .NET 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 permettant d'interagir avec les services compatibles GData, dans différents langages de programmation. 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 un ensemble d'exemples d'utilisations courantes de la version C# de la bibliothèque cliente, suivis d'autres informations sur l'écriture de clients GData. À la fin de ce document, vous trouverez un lien vers la documentation de référence de la bibliothèque cliente C#, au format NDoc.

Pour utiliser cette bibliothèque cliente, vous avez besoin du runtime .NET 1.1 et vous devez également appliquer tous les correctifs.

Téléchargez la bibliothèque cliente .NET.

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 .NET 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
  4. Référence

Audience

Ce document est destiné aux programmeurs C# 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 programmer en C#.

Présentation du modèle de données

La bibliothèque cliente C# fournit un ensemble de classes qui correspondent aux éléments et aux types de données 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 le code XML. Le moyen le plus simple d'y parvenir est d'utiliser une bibliothèque tierce appropriée.

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 GData à l'aide de la bibliothèque cliente C#.

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 l'instruction "using" suivante :

using Google.GData.Client;

Demander un flux

Comme décrit dans la documentation de l'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. 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 C# pour un utilisateur dont l'adresse e-mail est "jo@gmail.com" et le mot de passe "mypassword", utilisez le code suivant :

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

La classe Service 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 Service, 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. Appelez une méthode pour envoyer la requête et recevoir les résultats.

La méthode service.setUserCredentials définit la propriété service.Credentials avec un objet d'informations d'identification réseau .NET standard. Les identifiants sont définis sur 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 autres systèmes d'authentification, consultez la documentation sur l'authentification avec un compte Google.

Pour demander un flux entier, vous appelez la méthode service.Query, qui prend un objet FeedQuery 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 Service, Query gère l'authentification et les redirections si nécessaire.

Insérer un nouvel élément

Pour insérer un élément dans un flux Agenda, vous pouvez utiliser le code suivant :

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

Après avoir défini l'URL, nous construisons un objet AtomEntry.

Le titre de l'entrée est un AtomTextConstruct, 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 AtomContent, une classe qui peut contenir du texte brut ou d'autres formes de contenu, y compris des données XML et binaires.

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, ajoutez un objet AtomAuthor à la collection Authors de l'entrée.

Nous utilisons le même objet Service 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.

Le code ci-dessus équivaut à l'envoi de POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (avec une authentification appropriée) et à la fourniture d'une entrée.

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 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'URL d'une entrée.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

L'entrée insérée comporte une propriété, SelfUri, qui renvoie un objet AtomUri qui, à l'aide de sa méthode ToString(), peut être utilisé pour créer un nouvel objet URI.

Il ne nous reste plus qu'à appeler la méthode Query du service pour obtenir un nouvel objet AtomFeed, avec une seule entrée dans sa collection "Entries".

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

Rechercher une entrée

Pour récupérer la première correspondance dans une recherche en texte intégral, utilisez le code suivant :

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

Cet exemple commence par la construction d'un objet FeedQuery, 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 propriété.

Après avoir construit l'FeedQuery, 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 Query. Toutefois, la méthode FeedQuery fournit une couche d'abstraction utile pour que vous n'ayez pas à créer l'URL vous-même.

La collection Entries du flux renvoie une liste des entrées du flux, tandis que Entries.Count 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 AtomEntry. Nous utilisons ensuite la propriété Title de la classe AtomEntry pour récupérer le titre de l'entrée.

Le code ci-dessus équivaut à l'envoi de GET http://www.google.com/calendar/feeds/jo@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 :

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

La classe AtomCategory représente bien sûr une catégorie à utiliser dans un filtre de catégorie. La classe QueryCategory 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/jo@gmail.com/private/full/-/by_jo?q=Tennis à Agenda.

Mettre à jour un élément

Pour mettre à jour un élément existant, utilisez le code suivant. Dans l'exemple suivant, nous modifions le titre de l'entrée précédemment récupérée, en remplaçant l'ancien texte ("Tennis avec Beth") par "Réunion importante".

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

Nous définissons d'abord un nouveau titre pour l'entrée que nous avons récupérée précédemment. Il ne nous reste plus qu'à appeler la méthode Upate pour envoyer l'entrée mise à jour au service.

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 des entrées, consultez la section Simultanéité optimiste du document de référence du protocole v1.)

Le code ci-dessus équivaut à peu près à l'envoi de PUT http://www.google.com/calendar/feeds/jo@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 un élément existant, utilisez le code suivant :

updateEntry.Delete();

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/jo@gmail.com/private/full/entryID au service.

Utiliser les flux Google Agenda

Les exemples ci-dessus expliquent comment utiliser l'API Google Data C# pour travailler avec des flux GData génériques. Toutefois, lorsque vous travaillez avec un flux Google Agenda en particulier, celui-ci contient de nombreuses données spécifiques à l'agenda qui ne sont pas facilement accessibles à l'aide des objets standards orientés Atom dans la bibliothèque d'API de base. Pour vous aider à interagir avec ces flux, nous mettons à votre disposition les extensions suivantes :

using Google.GData.Extensions;
using Google.GData.Calendar;

L'espace de noms Extensions traite des extensions en général, tandis que l'espace de noms Calendar vous donne accès à un service d'agenda personnalisé, à un flux et à un objet de requête. Vous trouverez un exemple plus élaboré de l'utilisation de ces extensions dans le sous-répertoire /Samples de l'installation de l'API C#. Les objets suivants sont ajoutés :

EventQuery
Sous-classe de FeedQuery, qui vous permet de définir deux paramètres personnalisés pour le service Agenda (start-min et start-max).
CalendarService
Sous-classe de service, qui peut renvoyer un flux d'événements.
EventFeed
Sous-classe d'AtomFeed, qui expose les EventEntries.
EventEntry
Sous-classe d'AtomEntry, qui possède des propriétés supplémentaires liées aux données d'agenda.

Pour en savoir plus sur ces classes spéciales, consultez la documentation de l'API et l'exemple de programme.

Référence

Pour obtenir des informations de référence sur la bibliothèque cliente C#, consultez la documentation de référence.

Haut de page