Ce document explique comment utiliser la bibliothèque cliente .NET pour envoyer des requêtes 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, suivies 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 sur la bibliothèque cliente C#, au format NDoc.
Pour utiliser cette bibliothèque cliente, vous avez besoin de l'environnement d'exécution .NET 1.1 et vous devez également être à jour sur tous les correctifs.
Téléchargez la bibliothèque cliente .NET.
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 .NET avec l'API Data d'un service spécifique, consultez la documentation du service concerné. 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 C# 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 C#.
Présentation du modèle de données
La bibliothèque cliente C# fournit un ensemble de classes correspondant aux éléments et aux types de données 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.
Vous pouvez analyser et/ou générer le code XML vous-même si vous le souhaitez. Pour ce faire, le moyen le plus simple est d'utiliser une bibliothèque tierce appropriée.
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 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 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 l'instruction d'utilisation suivante:
using Google.GData.Client;
Demander un flux
Comme décrit dans la documentation de l'API de données Google Agenda, 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. 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 C#, utilisez le code suivant pour un utilisateur dont l'adresse e-mail est "jo@gmail.com" et le mot de passe "mypassword".
// 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. 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
Serviceen 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.
- 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'identifiants 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 Authentication for Installed Applications (Authentification pour les applications installées). Pour en savoir plus sur les autres systèmes d'authentification, consultez la documentation sur l'authentification des comptes 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 expliquerons ultérieurement comment envoyer des requêtes plus spécifiques 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 créons 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 pouvant 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 ignorons l'URI.) Pour ajouter un auteur à une entrée, vous devez ajouter 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 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.
Le code ci-dessus équivaut à envoyer POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (avec l'authentification appropriée) et à fournir 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 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 possède une propriété, SelfUri, qui renvoie un objet AtomUri qui, à l'aide de sa méthode ToString(), peut être utilisé pour créer un objet URI.
Il suffit ensuite d'appeler la méthode Query du service pour obtenir un nouvel objet AtomFeed, avec une seule entrée dans sa collection "Entrées".
Le code ci-dessus équivaut à envoyer GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID à 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 construire un objet FeedQuery, 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 propriété.
Après avoir construit le 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 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 Query. Toutefois, la méthode FeedQuery fournit une couche d'abstraction utile afin que vous n'ayez pas à créer l'URL vous-même.
La collection Entries du flux affiche une liste des entrées du flux. Entries.Count affiche 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 AtomEntry. Ensuite, nous utilisons la propriété Title de la classe AtomEntry pour récupérer le titre de l'entrée.
Le code ci-dessus équivaut à envoyer GET http://www.google.com/calendar/feeds/jo@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:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);
Bien entendu, la classe AtomCategory représente une catégorie à utiliser dans un filtre de catégorie. La classe QueryCategory 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/jo@gmail.com/private/full/-/by_jo?q=Tennis à Google Agenda.
Mettre à jour un élément
Pour mettre à jour un élément existant, utilisez le code suivant : Dans l'exemple suivant, nous remplaçons le titre de l'entrée précédemment récupérée de son ancien texte ("Tennis avec Beth") en "Réunion importante".
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Nous commençons par définir un nouveau titre pour l'entrée que nous avons récupérée précédemment. Il suffit ensuite d'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. (Pour plus d'informations sur les versions d'entrée, consultez la section Concurrence optimiste du document de référence sur le 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, avec la nouvelle entrée (au format Atom) pour remplacer l'entrée d'origine.
Suppression d'un élément
Pour supprimer un élément existant, utilisez le code suivant:
updateEntry.Delete();
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/jo@gmail.com/private/full/entryID au service.
Utilisation des flux Google Agenda
Les exemples ci-dessus décrivent comment utiliser l'API Google Data C# pour travailler avec des flux GData génériques. Toutefois, si vous utilisez un flux Google Agenda en particulier, le flux contient un grand nombre de données spécifiques à l'agenda qui ne sont pas facilement accessibles à l'aide des objets Atom standards de la bibliothèque d'API de base. Pour vous aider à interagir avec ces flux, nous proposons les extensions suivantes:
using Google.GData.Extensions; using Google.GData.Calendar;
L'espace de noms "Extensions" traite les extensions en général, tandis que l'espace de noms Agenda vous donne accès à un service d'agenda, un flux et un objet de requête personnalisés. Vous trouverez un exemple plus détaillé d'utilisation de ces extensions dans le sous-répertoire /Samples de l'installation de l'API C#. Les objets suivants sont ajoutés:
- Requête
- Sous-classe de FeedQuery qui vous permet de définir deux paramètres personnalisés pour le service Agenda (start-min et start-max).
- Service d'agenda
- Sous-classe de service pouvant renvoyer un flux d'événements.
- Flux d'événements
- Sous-classe d'AtomFeed exposant les entrées EventEntries.
- Entrée
- 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 le programme d'exemples.
Reference
Pour en savoir plus sur la bibliothèque cliente C#, consultez la documentation de référence.