En este documento, se describe cómo usar la biblioteca cliente de .NET para enviar consultas de la API de datos de Google ("GData") y cómo interpretar las respuestas que se muestran.
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 GData, enviarlas a un servicio y recibir respuestas.
En este documento, se proporciona un conjunto de ejemplos de usos comunes de la versión de C# de la biblioteca cliente, seguidos de otra información sobre la escritura de clientes de GData. Al final de este documento, hay un vínculo a la documentación de referencia para la biblioteca cliente de C#, en formato NDoc.
Para usar esta biblioteca cliente, necesitas el entorno de ejecución de .NET 1.1, y también debes estar actualizado en todos los parches.
Descarga la biblioteca cliente de .NET.
Los ejemplos de esta guía se refieren a la API del Calendario de Google, pero esta guía no es una guía precisa o actualizada para utilizar la API del Calendario. Para obtener información sobre el uso de 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 trabaja con Calendario, consulte la Guía para programadores de la API de datos de Calendario.
Contenido
Público
Este documento está destinado a programadores de C# que desean escribir aplicaciones cliente que pueden interactuar con servicios de GData.
En este documento, se asume que comprendes las ideas generales detrás del protocolo de las API de datos de Google. 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 API de datos de Google. Por ejemplo, hay una clase de feed, que corresponde al elemento <atom:feed>; tiene métodos para crear una entrada, obtener y configurar 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 API de datos de Google tienen su propia clase. Para obtener más detalles, consulte 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 muestra un objeto Feed con los valores resultantes.
Para enviar un feed o una entrada a un servicio, crea un objeto Feed o Entry, luego llama a un método de biblioteca (como el método insert) para traducir el objeto al formato XML de forma automática y enviarlo.
Si lo prefieres, puedes analizar o generar un archivo 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 datos de Google es extensible, el modelo de objetos correspondiente es extensible. Por ejemplo, la biblioteca cliente proporciona clases que corresponden a los elementos definidos en el espacio de nombres de datos de Google.
Instructivo y ejemplos
En los siguientes ejemplos, se muestra cómo enviar varias solicitudes de GData con la biblioteca cliente de C#.
Para hacerlos más concretos, estos ejemplos muestran cómo interactuar con un servicio específico: Calendario de Google. Te indicaremos los lugares en que Calendario difiere de otros servicios de Google para ayudarte a adaptar estos ejemplos para usarlos con otros servicios. Para obtener más información sobre Calendario, consulte la documentación de la API de datos de Calendario de Google.
Cómo compilar y ejecutar tu cliente
Para compilar los ejemplos de este documento, deberá usar la siguiente instrucción:
using Google.GData.Client;
Cómo solicitar un feed
Como se describe en la documentación de la API de datos de Calendario de Google, puedes solicitar un feed de Calendario si envías la siguiente solicitud HTTP a 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 Calendario para obtener más información. En cambio, puedes usar la URL predeterminada especial para interactuar con el Calendario (como se describe en el documento de Calendario), pero en este documento usaremos la URL del feed completo privado, que contiene el ID del usuario.
También debes proporcionar la autenticación adecuada. Ten en cuenta que el sistema de autenticación que utilizamos aquí (conocido como "Autenticación de Google para aplicaciones instaladas") es adecuado solo para usar en aplicaciones cliente instaladas, como clientes de escritorio, no para aplicaciones web. Para obtener más información sobre la autenticación, consulta la documentación de autenticación de cuenta de Google.
A fin de solicitar un feed de 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) con un servicio de GData. El procedimiento general para enviar una consulta a un servicio mediante la biblioteca cliente consta de los siguientes pasos:
- Obtén o construye la URL adecuada.
- Si envías datos a un servicio (por ejemplo, si vas a insertar una entrada nueva), transforma los datos sin procesar en objetos usando las clases de la biblioteca cliente. (Este paso no se aplica si solo solicitas un feed, como lo hacemos en este ejemplo).
- Crea una instancia nueva de
Servicey establece el nombre del servicio (como"cl"para Calendario) y el nombre de la aplicación (en el formatocompanyName-applicationName-versionID). - Configura 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 establecen en el ID y la contraseña del usuario en cuyo nombre tu cliente envía la consulta. En los ejemplos de este documento se utiliza el sistema de autenticación "Autenticación de aplicaciones instaladas". Para obtener más información acerca de otros sistemas de autenticación, consulta la documentación de autenticación de cuentas de Google.
Para solicitar un feed completo, debes llamar al método service.Query, que toma un objeto FeedQuery y muestra el feed completo que se encontró en esa URL. Le mostraremos cómo enviar consultas más específicas más adelante en este documento.
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 nuevo elemento
Para insertar un elemento en un feed de Calendario, puede 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 de varias formas (texto sin formato, HTML o XHTML). El contenido de la entrada está representado por un objeto AtomContent, una clase que puede contener texto sin formato o bien otras formas de contenido, incluidos los datos XML y binarios.
Cada autor se representa como un nombre, un URI y una dirección de correo electrónico. (en este ejemplo, no incluiremos el URI). Para agregar un autor a una entrada, debes agregar un objeto AtomAuthor a la colección Authors de la entrada.
Usaremos el mismo objeto Service que creamos en el ejemplo anterior. En este caso, el método que se llamará es Insert, que envía un elemento a la URL de inserción especificada.
El servicio muestra 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, la recuperación de esa entrada no es realmente necesaria, ya que Calendario ya mostró la entrada insertada, pero 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 muestra un objeto AtomUri que, mediante su método ToString(), se puede usar para crear un objeto URI nuevo.
Luego, solo debemos 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 es equivalente a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID a Calendario con la autenticación adecuada.
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;
}
Este ejemplo comienza con la construcción de un objeto FeedQuery, que consiste principalmente en una URL más parámetros de consulta asociados. Cada uno de los parámetros de consulta de GData estándar tiene una propiedad.
Después de construir el FeedQuery, lo pasamos al método Query del servicio, que muestra un feed que contiene los resultados de la consulta. Un enfoque alternativo sería construir una URL tú mismo (agregando parámetros de consulta 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 tú mismo.
La colección Entries del feed muestra una lista de las entradas del feed. Entries.Count muestra la cantidad de entradas del feed.
En este caso, si la consulta muestra algún resultado, asignaremos 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 es equivalente a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis a Calendario.
Consulta por categoría
Nota: Calendario de Google no asocia etiquetas con eventos, por lo que este ejemplo no funciona con Calendario.
Para recuperar un feed compuesto por todas las entradas que coinciden con la búsqueda de texto completo anterior y que pertenecen a una categoría o etiqueta particular, utilice el siguiente código:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);
La clase AtomCategory, por supuesto, representa una categoría que se usará en un filtro de categoría. La clase QueryCategory puede contener varias categorías, pero, en este caso, estamos construyendo un filtro con una sola categoría.
Luego, agregamos ese filtro a la consulta existente, que aún contiene la string de consulta de texto completo del ejemplo anterior.
Una vez más, usamos 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.
Actualizar un elemento
Para actualizar un elemento existente, usa el siguiente código. En el siguiente ejemplo, cambiaremos el título de la entrada recuperada de su texto anterior ("Tennis with Beth") a "Important meeting".
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 muestra la entrada actualizada, incluida una URL nueva 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 v1).
El código anterior equivale aproximadamente al envío de PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servicio, junto con la entrada nueva (en formato Atom) para reemplazar la entrada original.
Eliminar 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 estamos llamando al método Delete en lugar de Update.
El código anterior equivale aproximadamente al envío de DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servicio.
Cómo trabajar con feeds de Calendario de Google
En los ejemplos anteriores, se describe cómo usar la API de C# de datos de Google para trabajar con feeds genéricos de GData. Sin embargo, cuando trabajes con un feed de Calendario de Google, este tendrá 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 API de base. Para ayudarlo a interactuar con esos feeds, proporcionamos las siguientes extensiones:
using Google.GData.Extensions; using Google.GData.Calendar;
En general, el espacio de nombres de extensiones se ocupa de las extensiones; el espacio de nombres de Calendario te brinda acceso a un servicio de calendario, un feed y un objeto de consulta personalizados. Puedes encontrar un ejemplo más detallado de cómo se usan esas extensiones en el subdirectorio /Samples de la instalación de la API de C#. Se agregan los siguientes objetos:
- Consulta de evento
- Es una subclase de FeedQuery, que le permite establecer dos parámetros personalizados para el servicio de Calendario (start-min y start-max).
- Servicio de calendario
- Una subclase del servicio, que puede mostrar un feed de evento.
- Feed del evento
- Es una subclase de AtomFeed que expone EventEntries.
- Entrada de eventos
- 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.
Reference
Para obtener información de referencia sobre la biblioteca cliente de C#, consulta la documentación de referencia.