Este documento descreve como usar a biblioteca cliente Java para enviar consultas da API Google Data ("GData") e interpretar as respostas retornadas.

O Google oferece um conjunto de bibliotecas de cliente em várias linguagens de programação para interagir com serviços que têm APIs de dados. Usando essas bibliotecas, você pode criar solicitações GData, enviá-las para um serviço e receber respostas.

Este documento apresenta algumas informações gerais sobre o uso da biblioteca de cliente Java, além de um conjunto de exemplos de usos comuns.

Para usar essa biblioteca de cliente, você precisa executar o Java 1.5.

Faça o download da biblioteca de cliente do Java.

Os exemplos deste guia se referem à API Google Calendar, mas este não é um guia preciso ou atualizado para usar a API Calendar. Para informações sobre como usar a biblioteca de cliente Java com a API de dados de um serviço específico, consulte a documentação específica do serviço. Por exemplo, se você estiver trabalhando com o Agenda, leia o Guia do desenvolvedor da API Calendar Data.

Índice

Público-alvo

Este documento é destinado a programadores Java que querem criar aplicativos cliente que possam interagir com serviços GData.

Neste documento, presumimos que você entenda as ideias gerais por trás do protocolo das APIs de dados do Google. Ele também pressupõe que você saiba programar em Java.

Para informações de referência sobre as classes e os métodos fornecidos pela biblioteca de cliente, consulte a referência da API da biblioteca de cliente Java (no formato Javadoc).

Este documento foi criado para ser lido em ordem. Cada exemplo usa exemplos anteriores.

Visão geral do modelo de dados

A biblioteca cliente Java usa um conjunto de classes para representar os elementos usados pelas APIs de dados do Google. Por exemplo, há uma classe de feed, que corresponde ao elemento <atom:feed>. Ela tem métodos para criar uma entrada, receber e definir os valores de vários subelementos e assim por diante. Há também uma classe Entry, que corresponde ao elemento <atom:entry>. Nem todos os elementos definidos nas APIs de dados do Google têm a própria classe. Para mais detalhes, consulte a documentação de referência.

A biblioteca pode analisar automaticamente o conteúdo do Atom e colocar os valores dos elementos do Atom em objetos apropriados. Por exemplo, o método getFeed recebe um feed, o analisa e retorna um objeto Feed com os valores resultantes.

Para enviar um feed ou entrada a um serviço, crie um objeto Feed ou Entry e, em seguida, chame um método de biblioteca (como o método insert) para converter o objeto automaticamente em XML e enviá-lo.

Você pode analisar e/ou gerar XML por conta própria, se preferir. A maneira mais fácil de fazer isso é usar uma biblioteca de terceiros apropriada, como o Roma.

Assim como a sintaxe XML da API Google Data é extensível, o modelo de objeto correspondente é extensível. Por exemplo, a biblioteca de cliente fornece classes correspondentes aos elementos definidos no namespace de dados do Google.

Tutorial e exemplos

Os exemplos a seguir mostram como enviar várias solicitações de API de dados usando a biblioteca de cliente Java.

Para explicar melhor, estes exemplos mostram como interagir com um serviço específico: o Google Agenda. Vamos indicar locais em que o Google Agenda é diferente de outros Serviços do Google, para ajudar você a adaptar esses exemplos para uso com outros serviços. Para mais informações sobre o Agenda, consulte a documentação da API Google Calendar Data.

Como criar e executar o cliente

Para compilar os exemplos neste documento, é necessário usar as seguintes instruções de importação:

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;

Como solicitar um feed

Conforme descrito no documento API Google Data Data, você pode solicitar um feed do Agenda enviando a seguinte solicitação HTTP para o Agenda:

GET http://www.google.com/calendar/feeds/userID/private/full

É preciso substituir userID pelo endereço de e-mail do usuário. Veja mais detalhes no documento do Google Agenda. Em vez disso, você pode usar o URL padrão especial para interagir com o Agenda (conforme descrito no documento do Agenda). Nesse documento, usaremos o URL particular completo do feed, que contém o ID do usuário.

Você também precisa fornecer a autenticação apropriada. As principais diferenças entre este exemplo e o primeiro no documento do Agenda são que (1) o exemplo inclui autenticação e (2) este exemplo usa a classe GoogleService mais geral, em vez da classe CalendarService específica do Google Agenda.

O sistema de autenticação que estamos usando aqui (conhecido como "Autenticação do Google para aplicativos instalados") é apropriado apenas para uso em aplicativos clientes instalados, como clientes de desktop, não para uso em aplicativos da web. Para mais informações sobre autenticação, consulte a documentação Autenticação da Conta do Google.

Para solicitar um feed do Google Agenda usando a biblioteca de cliente Java, para um usuário com o endereço de e-mail "liz@gmail.com" e senha "mypassword", use o seguinte 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);

A classe GoogleService representa uma conexão de cliente (com autenticação) com um serviço GData. O procedimento geral para enviar uma consulta a um serviço usando a biblioteca de cliente consiste nas seguintes etapas:

1. Consiga ou construa o URL apropriado.
2. Se você estiver enviando dados para um serviço (por exemplo, se estiver inserindo uma nova entrada), transforme os dados brutos em objetos usando as classes da biblioteca de cliente. Essa etapa não se aplica se você está apenas solicitando um feed, como estamos fazendo neste exemplo.
3. Crie uma nova instância GoogleService, definindo o nome do serviço (como "cl" para o Agenda) e o nome do aplicativo (no formato companyName-applicationName-versionID).
4. Defina as credenciais apropriadas.
5. Indique à biblioteca cliente quais extensões o feed usará, para que a biblioteca possa analisar os feeds retornados corretamente.
6. Chame um método para enviar a solicitação e receber os resultados.

O método setUserCredentials especifica o ID e a senha do usuário em nome do qual o cliente está enviando a consulta. Os exemplos neste documento usam o sistema de autenticação "Autenticação para aplicativos instalados". Para mais informações sobre sistemas de autenticação, consulte a documentação Autenticação da Conta do Google.

Depois de definir as credenciais, você indica quais extensões o feed vai usar chamando o método declareExtensions. Neste caso, dizemos que o feed é de evento e, portanto, usará as extensões definidas pelo tipo de evento.

Para solicitar um feed inteiro, chame o método getFeed, que usa um URL e retorna todo o feed encontrado nesse URL. Mais adiante neste documento, vamos mostrar como enviar consultas mais específicas.

Como outros métodos da classe GoogleService, o getFeed processa a autenticação e os redirecionamentos conforme necessário.

Inserir um novo item

Para criar um novo evento da agenda, você pode usar o seguinte 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);

Depois de definir o URL, criamos um objeto EventEntry. O EventEntry é derivado da classe base abstrata BaseEntry, que também é a classe pai da Entry, que representa um elemento <atom:entry>.

A classe EventEntry representa um tipo de evento. Para mais informações, consulte o documento de tipos. Para outros serviços além do Agenda, atribua a entrada retornada a um objeto Entry em vez de a um objeto EventEntry.

O título da entrada é uma TextConstruct, uma classe que contém texto de várias formas (texto simples, HTML ou XHTML). O conteúdo de entrada é representado por um objeto Content, uma classe que pode conter texto simples ou outras formas de conteúdo, incluindo XML e dados binários. No entanto, o método setContent também aceita um TextConstruct.

Cada autor é representado como nome, URI e endereço de e-mail. Neste exemplo, deixamos de fora o URI. Para adicionar um autor a uma entrada, chame o método getAuthors().add da entrada.

Estamos usando o mesmo objeto GoogleService que criamos no exemplo anterior. Nesse caso, o método a ser chamado é insert, que envia um item para o URL de inserção especificado.

O serviço retorna a entrada recém-criada, que pode conter elementos adicionais gerados pelo servidor, como um URL de edição para a entrada.

Os códigos de status HTTP são retornados como exceções.

O código acima é equivalente a enviar POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (com autenticação adequada) e fornecer uma entrada na forma de um tipo de evento.

Como solicitar uma entrada específica

O código a seguir permite solicitar a entrada específica que você inseriu no exemplo anterior.

No contexto desta série de exemplos, recuperar essa entrada não é necessário porque o Google Agenda já retornou a entrada inserida, mas a mesma técnica pode ser aplicada sempre que você souber o URI de uma entrada.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

A entrada inserida tem um método, getSelfLink, que retorna um objeto Link que inclui o URL da entrada. A classe Link tem um método getHref que retorna o URL como um String, do qual podemos criar um objeto de URL.

Em seguida, precisamos chamar o método getEntry do serviço para receber a entrada.

Observe que usamos EventEntry.class como um parâmetro para getEntry, o que indica que esperamos que o serviço retorne um evento em vez de apenas uma entrada simples. Para outros serviços além do Agenda, transmita Entry.class.

O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID para o Google Agenda, com autenticação correta.

Como pesquisar entradas

Para recuperar a primeira correspondência de uma pesquisa de texto completo, use o seguinte 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();
}

Esse exemplo começa criando um objeto Query, que consiste principalmente em um URL e os parâmetros de consulta associados. Cada um dos parâmetros de consulta GData padrão tem um método setter. Também é possível definir parâmetros de consulta personalizados para um serviço específico, usando o método addCustomParameter.

Depois de construir o Query, vamos transmiti-lo ao método query do serviço, que retorna um feed contendo os resultados da consulta. Uma abordagem alternativa seria criar um URL por conta própria anexando parâmetros de consulta ao URL do feed e chamar o método getFeed. No entanto, o método query fornece uma camada útil de abstração para que você não precise criar o URL.

O método getEntries do feed retorna uma lista das entradas no feed, e getEntries().size retorna o número de entradas no feed.

Nesse caso, se a consulta retornar resultados, vamos atribuir o primeiro resultado correspondente a um objeto Entry. Em seguida, usamos o método getTitle().getPlainText da classe Entry para recuperar o título da entrada e convertê-lo em texto.

O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis para o Google Agenda.

Consultar por categoria

Observação: como o Google Agenda não associa marcadores a eventos, esse exemplo não funciona com ele.

Para recuperar um feed com todas as entradas que correspondam à pesquisa de texto completo anterior e que estejam em uma determinada categoria ou tenham um rótulo específico, use o seguinte código:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

A classe Category, é claro, representa uma categoria a ser usada em um filtro de categoria. A classe Query.CategoryFilter pode conter várias categorias, mas, neste caso, estamos criando um filtro com apenas uma categoria.

Em seguida, adicionamos esse filtro à consulta existente, que ainda contém a string de consulta de texto completo do exemplo anterior.

Usamos novamente o método query para enviar a consulta ao serviço.

Se o Google Agenda permitir uma pesquisa de categoria, o código acima será equivalente ao envio de GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis para o Google Agenda.

Como atualizar um item

Para atualizar um item existente, use o código a seguir. Neste exemplo, o título da entrada recuperada anteriormente de "Tennis with Darcy" foi alterado para "Reunião importante".

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

Primeiro, definimos um novo título para a entrada que buscamos anteriormente. Em seguida, recebemos o URL de edição para a entrada, usando o método getEditLink. Em seguida, chamamos o método update do serviço para enviar a entrada atualizada.

O serviço retorna a entrada atualizada, incluindo um novo URL para a nova versão desta entrada. Para mais informações sobre as versões de entrada, consulte a seção Simultaneidade otimista do documento de referência de protocolo.

O código acima é aproximadamente equivalente ao envio de PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ao serviço, junto com a nova entrada (no formato Atom) para substituir a entrada original.

Excluir um item

Para excluir a entrada atualizada, use o seguinte código:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

O URL a ser usado para exclusão é igual ao URL de edição. Portanto, este exemplo é muito semelhante ao anterior, exceto que obviamente estamos chamando o método delete em vez de update.

O código acima é aproximadamente equivalente ao envio de DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID ao serviço.

Referência

Para informações de referência sobre as classes e os métodos fornecidos pela biblioteca de cliente, consulte a referência da API da biblioteca de cliente Java (no formato Javadoc).

Voltar ao início