En este documento, se describe cómo usar la biblioteca cliente de Java para enviar consultas de la API de datos de Google ("GData") e interpretar las respuestas que se muestran.
Google proporciona un conjunto de bibliotecas cliente, en una variedad de lenguajes de programación, para interactuar con los servicios que tienen API de datos. Con estas bibliotecas, puedes crear solicitudes GData, enviarlas a un servicio y recibir respuestas.
En este documento, se proporciona información general sobre el uso de la biblioteca cliente de Java, junto con un conjunto de ejemplos de usos comunes.
Para usar esta biblioteca cliente, debes ejecutar Java 1.5.
Descarga la biblioteca cliente de Java.
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 Java 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á dirigido a programadores de Java que deseen escribir aplicaciones cliente que puedan 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 Java.
Para obtener información de referencia sobre las clases y los métodos proporcionados por la biblioteca cliente, consulta la referencia de la API de la biblioteca cliente de Java (en formato Javadoc).
Este documento está diseñado para leerse en orden. Cada ejemplo se basa en ejemplos anteriores.
Descripción general del modelo de datos
La biblioteca cliente de Java usa un conjunto de clases para representar los elementos 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 tú mismo. La forma más sencilla de hacerlo es con una biblioteca de terceros adecuada, como Roma.
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 a la API de datos con la biblioteca cliente de Java.
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ás usar las siguientes instrucciones de importación:
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;
Cómo solicitar un feed
Como se describe en el documento API de datos del Calendario de Google, puedes solicitar un feed del Calendario mediante el envío de 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 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. Las principales diferencias entre este ejemplo y el primer ejemplo del documento de Calendario son que (1) este ejemplo incluye autenticación y (2) este ejemplo usa la clase GoogleService más general en lugar de la clase específica Calendar.
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.
Si deseas solicitar un feed de Calendario con la biblioteca cliente de Java para un usuario con la dirección de correo electrónico "liz@gmail.com" y la contraseña "mypassword", usa el siguiente código:
// 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 clase GoogleService 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
GoogleServicey 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.
- Indica a la biblioteca cliente qué extensiones usará el feed para que la biblioteca pueda analizar los feeds que se muestran correctamente.
- Llama a un método para enviar la solicitud y recibir los resultados.
El método setUserCredentials especifica 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 de autenticación para aplicaciones instaladas. Para obtener más información acerca de los sistemas de autenticación, consulta la documentación de Autenticación de cuentas de Google.
Después de configurar las credenciales, llama al método declareExtensions para indicar qué extensiones usará el feed. En este caso, decimos que el feed es un feed de evento y, por lo tanto, usará las extensiones definidas por el tipo de evento.
Para solicitar un feed completo, debes llamar al método getFeed, que toma una URL 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 GoogleService, getFeed controla la autenticación y los redireccionamientos según sea necesario.
Cómo insertar un nuevo elemento
Para crear un nuevo evento del calendario, puedes usar el siguiente código:
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);
Después de configurar la URL, construimos un objeto EventEntry; EventEntry se deriva de la clase base abstracta BaseEntry, que también es la clase superior para la clase Entry, que representa un elemento <atom:entry>.
La clase EventEntry representa un tipo de evento. Para obtener más información, consulta el documento de tipos. Para servicios que no sean de Calendario, puedes asignar la entrada que se muestra a un objeto Entry en lugar de a un objeto EventEntry.
El título de la entrada es un TextConstruct, una clase que contiene texto de varias formas (texto sin formato, HTML o XHTML). El contenido de la entrada está representado por un objeto Content, una clase que puede contener texto sin formato o bien otras formas de contenido, incluidos los datos XML y binarios. (Sin embargo, el método setContent también puede aceptar una TextConstruct).
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 llamar al método getAuthors().add de la entrada.
Usaremos el mismo objeto GoogleService 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.
Los códigos de estado HTTP se muestran como excepciones.
El código anterior es equivalente a enviar POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (con la autenticación adecuada) y proporcionar una entrada en forma de un tipo de evento.
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 es posible aplicar la misma técnica siempre que conozcas el URI de una entrada.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
La entrada insertada tiene un método, getSelfLink, que muestra un objeto Link que incluye la URL de la entrada. La clase Link tiene un método getHref que muestra la URL como String, desde la cual podemos crear un objeto URL.
Luego, solo debemos llamar al método getEntry del servicio para obtener la entrada.
Ten en cuenta que proporcionamos EventEntry.class como parámetro a getEntry, lo que indica que esperamos que el servicio muestre un evento en lugar de una simple entrada. Para otros servicios que no sean Calendario, puede usar Entry.class.
El código anterior es equivalente a enviar GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID a Calendario con la autenticación adecuada.
Busca entradas
Para recuperar la primera coincidencia de una búsqueda de texto completo, usa el siguiente código:
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();
}
Este ejemplo comienza con la construcción de un objeto Query, 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 un método set. También puedes establecer parámetros de búsqueda personalizados para un servicio en particular mediante el método addCustomParameter.
Después de construir el Query, 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 getFeed, pero el método query proporciona una capa útil de abstracción para que no tengas que construir la URL tú mismo.
El método getEntries del feed muestra una lista de las entradas del feed. getEntries().size 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 Entry. Luego, usamos el método getTitle().getPlainText de la clase Entry para recuperar el título de la entrada y convertirlo en texto.
El código anterior es equivalente a enviar GET http://www.google.com/calendar/feeds/liz@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:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);
La clase Category, por supuesto, representa una categoría que se usará en un filtro de categoría. La clase Query.CategoryFilter 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/liz@gmail.com/private/full/-/by_liz?q=Tennis a Calendario.
Actualizar un elemento
Para actualizar un elemento existente, usa el siguiente código. En este ejemplo, cambiamos el título de la entrada recuperada de su texto anterior ("Tennis with Darcy") a "Reunión importante".
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Primero, establecemos un nuevo título para la entrada que recuperamos antes. Luego, obtenemos la URL de edición de la entrada mediante el método getEditLink. Luego, llamamos al método update del servicio para enviar la entrada actualizada.
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 sobre simultaneidad optimista del documento de referencia del protocolo).
El código anterior equivale aproximadamente al envío de PUT http://www.google.com/calendar/feeds/liz@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 la entrada actualizada, usa el siguiente código:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
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/liz@gmail.com/private/full/entryID al servicio.
Reference
Para obtener información de referencia sobre las clases y los métodos proporcionados por la biblioteca cliente, consulta la referencia de la API de la biblioteca cliente de Java (en formato Javadoc).