Artigo Java Magazine 67 - Google Data APIs: Calendar 2.0

Para que serve:

As APIs de Dados Google possibilitam a integração das nossas aplicações com os diversos serviços Google. Utilizando a Java Cliente Library, nossas aplicações Java têm acesso a essa funcionalidade de forma simples. Utilizando a API de Agenda podemos, dentre outras coisas, criar e editar agendas e eventos.

Em que situação o tema é útil:

Utilizar serviços já existentes e robustos é sempre uma boa alternativa, principalmente nos dias de hoje, onde temos a constante necessidade de integração entre os diversos serviços existentes. Podemos utilizar a API de Agenda para sincronizar eventos com alguma aplicação desktop para uso offline ou simplesmente para criar um módulo de eventos num site de baladas. Enfim, existem vários possíveis cenários onde seria interessante ter um módulo de gerenciamento de eventos.

Google Data APIs – Calendar:

A API de Agenda, que está em sua versão 2.0, é parte do conjunto de APIs de Dados fornecidos pelo Google. Com essa API conseguimos criar novas agendas, subscrever o usuário em agendas de outros usuários, criar e editar eventos, criar lembretes (reminders) para os eventos, dentre outras funcionalidades.

Utilizando as classes fornecidas pela Java Client Library, não é preciso se preocupar com detalhes de protocolo. Para interagir com a API de Agenda temos a classe CalendarService. Essa classe abstrai todo o protocolo do serviço e permite que o usuário use esses serviços como se estivesse invocando métodos locais. Para inserir um evento, por exemplo, basta criar um objeto CalendarEventEntry e passá-lo como parâmetro para o método CalendarService.insert().

Dessa maneira conseguimos utilizar os serviços da API sem precisar nos preocupar com os detalhes de protocolo.

Dando continuidade ao nosso “passeio” pelas APIs de Dados Google[1], veremos agora como integrar nossas aplicações Java com mais um serviço, o Google Calendar (Google Agenda no Brasil), através do uso da Google Calendar Data API.

Recentemente o protocolo GData foi atualizado e agora está na versão 2.0. Com isso, a maioria das APIs – inclusive as APIs Google Calendar (tema deste artigo) e Google Contacts (tema do artigo anterior) – também sofreram alterações[2]. Veremos, no entanto, que para quem utiliza a Java Client Library – ou outra biblioteca cliente qualquer – as alterações são mínimas, visto que essas bibliotecas abstraem os detalhes do protocolo. Neste artigo, utilizaremos a versão 2.0 da Google Calendar Data API e não nos preocuparemos aqui em realizar comparações com a versão anterior da API.

Assim como foi feito no artigo anterior, “Google Data APIs: Contacts”, mostraremos como efetuar as principais operações disponibilizadas pela API de Agenda[3] tanto em nível de protocolo, onde veremos os exemplos dos dados trocados entre a aplicação cliente e o servidor, quanto através de exemplos práticos utilizando a Java Client Library (biblioteca cliente Java).

No artigo anterior, demos início à construção de uma aplicação Swing que visa demonstrar de forma prática os conceitos discutidos ao longo do estudo sobre as APIs de Dados. O nosso “Organizador Pessoal”[4] atualmente é capaz de gerenciar os contatos de um usuário e organizar esses contatos em grupos. Ao decorrer deste artigo, daremos continuidade à construção da nossa aplicação, acrescentando a funcionalidade de agenda de compromissos.

Google Calendar Data API

A Google Calendar Data API (API de Dados de Agenda Google), assim como as demais APIs de dados, provê ao desenvolvedor um conjunto de métodos responsáveis por permitir a interação entre uma aplicação terceira e um serviço Google, nesse caso o Google Calendar. Com ela podemos, entre outras coisas: gerenciar a lista de agendas de um usuário; gerenciar os eventos pertencentes a essas agendas, bem com os comentários relacionados a cada evento; subscrever o usuário em agendas públicas de outros usuários; compartilhar suas agendas com outros usuários e também configurar lembretes para os eventos. Um único artigo é pouco para descrever e mostrar exemplos de todas essas funcionalidades, mas tentaremos aqui, explorar as principais delas.

Na API de Agenda lidamos com quatro tipos diferentes de feeds e, consequentemente, de entradas (entries). A Tabela 1 mostra a descrição de cada um desses tipos e também as classes correspondentes na Java Client Library. Neste artigo analisaremos os feeds de agendas, eventos e comentários.

Tabela 1. Tipos de feed utilizados pela API de Agenda Google.

Autenticação

Nos artigos anteriores vimos as diferentes formas de autenticação suportadas pelas APIs de dados Google: AuthSub, Client Login (utilizada em nossos exemplos) e OAuth. No entanto, a API de Agenda oferece suporte a um tipo de autenticação especial, através da qual não precisamos informar, em momento algum, as credenciais do usuário. Esse tipo de autenticação é chamado de “Magic Cookie Authentication”, que como o próprio nome sugere é baseado num “cookie mágico”, ou seja, uma chave única gerada pelo servidor que pode ser usada para se ter acesso direto à lista de eventos de uma determinada agenda. A URL do feed utilizando esse tipo de autenticação se parece com a seguinte:

http://www.google.com/calendar/feeds/<calendarId>/private-<magicCookie>/basic

Para obter essa URL mágica siga os passos abaixo:

1.      Acesse o site do Google Calendar (calendar.google.com);

2.      Na lista de agendas à esquerda, escolha a agenda para a qual deseja obter a URL de acesso, clique na seta que se encontra ao lado do nome da agenda e escolha a opção “Calendar Settings”;

3.      Na tela de configurações da agenda, vá até a seção “Private Access” e clique no botão “XML” (ver Figura 1) que o endereço será exibido.

Copie o endereço e cole num browser de sua preferência para verificar que se trata de um feed válido. Perceba ainda que a URL padrão termina pela palavra basic, que indica o valor de projeção do feed. Esse valor pode ser substituído por algum dos demais valores de projeção disponíveis, como full, por exemplo. Mais adiante falaremos com mais detalhes dos valores de projeção suportados.

Figura 1. Tela para obtenção do magic cookie.

Feeds de Agendas

O serviço Google Agenda permite ao usuário agrupar seus eventos em diferentes agendas. Isso ajuda na organização e visualização dos eventos. A Figura 2 mostra a tela principal do Google Agenda. Note que à esquerda temos duas listas, “My Calendars” e “Other Calendars”, que representam, respectivamente, as agendas pertencentes ao usuário e as outras nas quais este se subscreveu. São exatamente essas agendas que acessamos através da API GData.

Os feeds de Agenda serão os primeiros que analisaremos neste artigo. Eles são utilizados justamente para a manipulação das agendas de um determinado usuário. Isto é, utilizando esses feeds podemos listar (com ou sem filtros), criar, atualizar e apagar as agendas do usuário, além de subscrever o usuário em agendas públicas de outros usuários.

Podemos interagir com a lista de agendas do usuário de três maneiras. Vejamos cada uma delas:

·         metafeed – Feed privado somente para leitura que contém a lista de agendas às quais o usuário tem acesso. É acessado através da seguinte URL: http://www.google.com/calendar/feeds/default;

·         allcalendars – Feed privado para leitura e escrita, usado para subscrições e personalizações das agendas do usuário. Inclui todas as agendas às quais o usuário tem Acesso. É acessado pela seguinte URL: http://www.google.com/calendar/feeds/default/allcalendars/full;

·         owncalendars – Feed privado para leitura e escrita, usado para gerenciar as agendas pertencentes ao usuário, ou seja, as agendas sobre as quais o usuário tem a permissão de owner. Um usuário se torna o owner de um calendário quando este é criado por ele ou quando outro usuário (que já é owner) concede tal permissão. Esse feed retorna apenas as agendas gerenciadas pelo usuário. É acessado pela seguinte URL: http://www.google.com/calendar/feeds/default/owncalendars/full;

Operações como insert() e delete() apresentam comportamentos diferentes de acordo com o tipo de feed utilizado. Quando utilizamos o feed owncalendars, insert() e delete() servem para criar e apagar uma entrada de agenda no feed. No caso do delete(), o usuário precisar ser owner da agenda. Já quando utilizamos o feed allcalendars, insert() e delete() são responsáveis por subscrever o usuário numa agenda pública já existente e cancelar a subscrição, respectivamente. Nesse caso, o calendário deve possuir um ID válido mesmo para fazer um insert().

A Listagem 1 mostra como se parece uma entrada de agenda. A maioria dos elementos já foi vista nos artigos anteriores. Temos os elementos básicos do Atom e Atom Publishing Protocol, prefixados com o namespace atom e app, respectivamente; elementos do GData Protocol, com o namepace gd e os elementos específicos da Calendar API, com o prefixo gCal. A Tabela 2 mostra os principais elementos do namespace gCal. Para a lista completa com a descrição detalhada dos valores possíveis, consulte a documentação oficial (ver seção Links).

Na API de Agenda, o elemento <atom:author> é obrigatório.

<atom:entry>

  <atom:id>http://www.google.com/calendar/feeds/default/calendars/user%40gmail.com</atom:id>

  <atom:published>2008-12-19T01:21:13.889Z</atom:published>

  <atom:updated>2008-12-11T05:12:51.000Z</atom:updated>

  <app:edited xmlns:app='http://www.w3.org/2007/app'>2008-12-11T05:12:51.000Z</app:edited>

  <atom:title type='text'>Minha Agenda</atom:title>

  <atom:summary type='text'>Descrição da Agenda...</atom:summary>

  <atom:content type='application/atom+xml'

      src='http://www.google.com/calendar/feeds/user%40gmail.com/private/full'/>

  <atom:link rel='alternate' type='application/atom+xml'

      href='http://www.google.com/calendar/feeds/user%40gmail.com/private/full'/>

  <atom:link rel='http://schemas.google.com/acl/2007#accessControlList'

      type='application/atom+xml'

      href='http://www.google.com/calendar/feeds/user%40gmail.com/acl/full'/>

  <atom:link rel='self' type='application/atom+xml'

      href='http://www.google.com/calendar/feeds/default/owncalendars/full/user%40gmail.com'/>

  <atom:link rel='edit' type='application/atom+xml'

      href='http://www.google.com/calendar/feeds/default/owncalendars/full/user%40gmail.com'/> ...