En este documento, se describe cómo usar la biblioteca cliente de .NET para enviar consultas a la API de Google Data ("GData") y cómo interpretar las respuestas que se devuelven.
Google proporciona un conjunto de bibliotecas cliente para interactuar con los servicios habilitados para GData en una variedad de lenguajes de programación. Con estas bibliotecas, puedes crear solicitudes de GData, enviarlas a un servicio y recibir respuestas.
En este documento, se proporciona un conjunto de ejemplos de usos comunes de la versión en C# de la biblioteca cliente, seguido de otra información sobre la escritura de clientes de GData. Al final de este documento, se incluye un vínculo a la documentación de referencia de la biblioteca cliente de C#, en formato NDoc.
Para usar esta biblioteca cliente, necesitas el tiempo de ejecución de .NET 1.1 y también debes tener instalados todos los parches más recientes.
Descarga la biblioteca cliente de .NET.
Los ejemplos de esta guía hacen referencia a la API de Google Calendar, pero esta guía no es una guía precisa ni actualizada para usar la API de Calendar. Para obtener información sobre cómo usar la biblioteca cliente de .NET con la API de datos de un servicio específico, consulta la documentación específica del servicio. Por ejemplo, si trabajas con Calendar, lee la Guía para desarrolladores de la API de Calendar Data.
Contenido
Público
Este documento está dirigido a programadores de C# que deseen escribir aplicaciones cliente que puedan interactuar con los servicios de GData.
En este documento, se supone que comprendes las ideas generales detrás del protocolo de las APIs de Google Data. También se supone que sabes programar en C#.
Descripción general del modelo de datos
La biblioteca cliente de C# proporciona un conjunto de clases que corresponden a los elementos y tipos de datos que usan las APIs de Google Data. Por ejemplo, hay una clase Feed, que corresponde al elemento <atom:feed>; tiene métodos para crear una entrada, obtener y establecer los valores de varios subelementos, y así sucesivamente. También hay una clase Entry, que corresponde al elemento <atom:entry>. No todos los elementos definidos en las APIs de datos de Google tienen su propia clase. Para obtener más detalles, consulta la documentación de referencia.
La biblioteca puede analizar automáticamente el contenido de Atom y colocar los valores de los elementos de Atom en objetos apropiados. Por ejemplo, el método getFeed obtiene un feed, lo analiza y devuelve un objeto Feed con los valores resultantes.
Para enviar un feed o una entrada a un servicio, crea un objeto Feed o Entry y, luego, llama a un método de la biblioteca (como el método insert) para traducir automáticamente el objeto a XML y enviarlo.
Si lo prefieres, puedes analizar o generar XML por tu cuenta. La forma más sencilla de hacerlo es con una biblioteca de terceros adecuada.
Así como la sintaxis XML de la API de Google Data es extensible, el modelo de objeto correspondiente también lo es. Por ejemplo, la biblioteca cliente proporciona clases correspondientes a los elementos definidos en el espacio de nombres de Google Data.
Instructivo y ejemplos
En los siguientes ejemplos, se muestra cómo enviar varias solicitudes de GData con la biblioteca cliente de C#.
Para que sean más concretos, estos ejemplos muestran cómo interactuar con un servicio específico: el Calendario de Google. Te mostraremos los lugares en los que Calendario difiere de otros servicios de Google para ayudarte a adaptar estos ejemplos y usarlos con otros servicios. Para obtener más información sobre Calendar, consulta la documentación de la API de Google Calendar Data.
Compila y ejecuta tu cliente
Para compilar los ejemplos de este documento, deberás usar la siguiente instrucción using:
using Google.GData.Client;
Cómo solicitar un feed
Como se describe en la documentación de la API de Google Calendar Data, puedes solicitar un feed del Calendario enviando la siguiente solicitud HTTP al Calendario:
GET http://www.google.com/calendar/feeds/userID/private/full
Por supuesto, debes reemplazar userID por la dirección de correo electrónico del usuario. Consulta el documento de Calendar para obtener más detalles. En su lugar, puedes usar la URL predeterminada especial para interactuar con Calendar (como se describe en el documento de Calendar), pero en este documento usaremos la URL del feed completo privado, que contiene el ID de usuario.
También debes proporcionar la autenticación adecuada. Ten en cuenta que el sistema de autenticación que usamos aquí (conocido como "Autenticación de Google para aplicaciones instaladas") solo es adecuado para su uso en aplicaciones cliente instaladas, como clientes de escritorio, y no para su uso en aplicaciones web. Para obtener más información sobre la autenticación, consulta la documentación de Autenticación de la Cuenta de Google.
Para solicitar un feed del Calendario con la biblioteca cliente de C#, para un usuario con la dirección de correo electrónico "jo@gmail.com" y la contraseña "mypassword", usa el siguiente código:
// 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 clase Service representa una conexión de cliente (con autenticación) a un servicio de GData. El procedimiento general para enviar una consulta a un servicio con la biblioteca cliente consta de los siguientes pasos:
- Obtén o crea la URL adecuada.
- Si envías datos a un servicio (por ejemplo, si insertas una entrada nueva), transforma los datos sin procesar en objetos con las clases de la biblioteca cliente. (Este paso no se aplica si solo solicitas un feed, como hacemos en este ejemplo).
- Crea una instancia de
Servicenueva y configura el nombre del servicio (por ejemplo,"cl"para Calendar) y el nombre de tu aplicación (con el formatocompanyName-applicationName-versionID). - Establece las credenciales adecuadas.
- Llama a un método para enviar la solicitud y recibir los resultados.
El método service.setUserCredentials establece la propiedad service.Credentials con un objeto de credenciales de red de .NET estándar.
Las credenciales se configuran con el ID y la contraseña del usuario en cuyo nombre tu cliente envía la consulta. En los ejemplos de este documento, se usa el sistema de autenticación "Autenticación para aplicaciones instaladas". Para obtener más información sobre otros sistemas de autenticación, consulta la documentación de Autenticación de la Cuenta de Google.
Para solicitar un feed completo, llama al método service.Query, que toma un objeto FeedQuery y devuelve el feed completo que se encuentra en esa URL. Más adelante en este documento, mostraremos cómo enviar consultas más específicas.
Al igual que otros métodos de la clase Service, Query controla la autenticación y los redireccionamientos según sea necesario.
Cómo insertar un elemento nuevo
Para insertar un elemento en un feed del Calendario, puedes usar el siguiente código:
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);Después de configurar la URL, construimos un objeto AtomEntry.
El título de la entrada es un AtomTextConstruct, una clase que contiene texto en varias formas (texto sin formato, HTML o XHTML). El contenido de la entrada se representa con un objeto AtomContent, una clase que puede contener texto sin formato o cualquier otro tipo de contenido, incluidos datos XML y binarios.
Cada autor se representa como un nombre, un URI y una dirección de correo electrónico. (En este ejemplo, omitimos el URI). Para agregar un autor a una entrada, agrega un objeto AtomAuthor a la colección Authors de la entrada.
Usamos el mismo objeto Service que creamos en el ejemplo anterior. En este caso, el método que se debe llamar es Insert, que envía un elemento a la URL de inserción especificada.
El servicio devuelve la entrada recién creada, que puede contener elementos adicionales generados por el servidor, como una URL de edición para la entrada.
El código anterior es equivalente a enviar POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (con la autenticación adecuada) y proporcionar una entrada.
Cómo solicitar una entrada específica
El siguiente código te permite solicitar la entrada específica que insertaste en el ejemplo anterior.
En el contexto de esta serie de ejemplos, no es necesario recuperar esa entrada, ya que Calendar ya devolvió la entrada insertada. Sin embargo, se puede aplicar la misma técnica siempre que conozcas la URL de una entrada.
FeedQuery singleQuery = new FeedQuery(); singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); AtomFeed newFeed = service.Query(singleQuery); AtomEntry retrievedEntry = newFeed.Entries[0];
La entrada insertada tiene una propiedad, SelfUri, que devuelve un objeto AtomUri que, con su método ToString(), se puede usar para crear un nuevo objeto URI.
Luego, solo tenemos que llamar al método Query del servicio para obtener un nuevo objeto AtomFeed, con solo una entrada en su colección Entries.
El código anterior equivale a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID a Calendar con la autenticación adecuada.
Cómo buscar una entrada
Para recuperar la primera coincidencia en una búsqueda de texto completo, usa el siguiente código:
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;
}En este ejemplo, primero se construye un objeto FeedQuery, que consta principalmente de una URL y parámetros de consulta asociados. Cada uno de los parámetros de consulta estándar de GData tiene una propiedad.
Después de construir el FeedQuery, lo pasamos al método Query del servicio, que devuelve un feed que contiene los resultados de la búsqueda. Un enfoque alternativo sería construir una URL por tu cuenta (agregando parámetros de búsqueda a la URL del feed) y, luego, llamar al método Query, pero el método FeedQuery proporciona una capa útil de abstracción para que no tengas que construir la URL por tu cuenta.
La colección Entries del feed devuelve una lista de las entradas del feed; Entries.Count devuelve la cantidad de entradas del feed.
En este caso, si la búsqueda devolvió algún resultado, asignamos el primer resultado coincidente a un objeto AtomEntry. Luego, usamos la propiedad Title de la clase AtomEntry para recuperar el título de la entrada.
El código anterior equivale a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis al Calendario.
Consultas por categoría
Nota: El Calendario de Google no asocia etiquetas con los eventos, por lo que este ejemplo no funciona con el Calendario.
Para recuperar un feed que consta de todas las entradas que coinciden con la búsqueda de texto completo anterior y que se encuentran en una categoría en particular o tienen una etiqueta en particular, usa el siguiente código:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);Por supuesto, la clase AtomCategory representa una categoría que se usará en un filtro de categorías. La clase QueryCategory puede contener varias categorías, pero, en este caso, crearemos un filtro con solo una categoría.
Luego, agregamos ese filtro a la consulta existente, que aún contiene la cadena de consulta de texto completo del ejemplo anterior.
Volvemos a usar el método Query para enviar la consulta al servicio.
Si Calendario permitiera una búsqueda por categoría, el código anterior sería equivalente a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis a Calendario.
Cómo actualizar un elemento
Para actualizar un elemento existente, usa el siguiente código. En el siguiente ejemplo, cambiamos el título de la entrada recuperada anteriormente de su texto anterior (“Tenis con Ana”) a “Reunión importante”.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Primero, establecemos un nuevo título para la entrada que recuperamos antes. Luego, solo llamamos al método Upate para enviar la entrada actualizada al servicio.
El servicio devuelve la entrada actualizada, incluida una nueva URL para la nueva versión de esta entrada. (Para obtener más información sobre las versiones de entrada, consulta la sección Simultaneidad optimista del documento de referencia del protocolo de la versión 1).
El código anterior es aproximadamente equivalente a enviar PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servicio, junto con la nueva entrada (en formato Atom) para reemplazar la entrada original.
Cómo borrar un elemento
Para borrar un elemento existente, usa el siguiente código:
updateEntry.Delete();
La URL que se usa para la eliminación es la misma que la URL de edición, por lo que este ejemplo es muy similar al anterior, excepto que, por supuesto, llamamos al método Delete en lugar de Update.
El código anterior es aproximadamente equivalente a enviar DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servicio.
Cómo trabajar con feeds del Calendario de Google
En los ejemplos anteriores, se describe cómo usar la API de Google Data C# para trabajar con feeds genéricos de GData. Sin embargo, cuando trabajas con un feed de Calendario de Google en particular, el feed contiene muchos datos específicos del calendario a los que no se puede acceder fácilmente con los objetos estándar orientados a Atom en la biblioteca de la API base. Para ayudarte a interactuar con esos feeds, te proporcionamos las siguientes extensiones:
using Google.GData.Extensions; using Google.GData.Calendar;
El espacio de nombres de Extensions se ocupa de las extensiones en general, mientras que el espacio de nombres de Calendar te brinda acceso a un servicio de calendario, un feed y un objeto de consulta personalizados. Puedes encontrar un ejemplo más elaborado de cómo se usan esas extensiones en el subdirectorio /Samples de la instalación de la API de C#. Se agregaron los siguientes objetos:
- EventQuery
- Una subclase de FeedQuery que te permite establecer dos parámetros personalizados para el servicio de Calendar (start-min y start-max).
- CalendarService
- Es una subclase de servicio que puede devolver un feed de eventos.
- EventFeed
- Es una subclase de AtomFeed que expone EventEntries.
- EventEntry
- Es una subclase de AtomEntry que tiene propiedades adicionales relacionadas con los datos del calendario.
Para obtener más detalles sobre esas clases especiales, consulta la documentación de la API y el programa de muestras.
Referencia
Para obtener información de referencia sobre la biblioteca cliente de C#, consulta la documentación de referencia.