Neste documento, descrevemos como usar a biblioteca de cliente .NET para enviar consultas da API Google Data ("GData") e interpretar as respostas retornadas.
O Google oferece um conjunto de bibliotecas de cliente para interagir com serviços compatíveis com GData em várias linguagens de programação. Com essas bibliotecas, é possível criar solicitações do GData, enviá-las a um serviço e receber respostas.
Este documento fornece um conjunto de exemplos de usos comuns da versão em C# da biblioteca de cliente, seguidos de outras informações sobre como escrever clientes GData. No final deste documento, há um link para a documentação de referência da biblioteca de cliente C#, no formato NDoc.
Para usar essa biblioteca de cliente, você precisa do runtime do .NET 1.1 e também precisa estar atualizado com todos os patches.
Faça o download da biblioteca de cliente do .NET.
Os exemplos deste guia se referem à API Google Agenda, mas ele não é um guia preciso ou atualizado para usar essa API. Para informações sobre como usar a biblioteca de cliente .NET com a API Data de um serviço específico, consulte a documentação do serviço. Por exemplo, se você estiver trabalhando com o Google Agenda, leia o guia do desenvolvedor da API de dados do Google Agenda.
Índice
Público-alvo
Este documento é destinado a programadores em C# que querem escrever aplicativos cliente capazes de interagir com os serviços do GData.
Este documento pressupõe que você entenda as ideias gerais por trás do protocolo das APIs Google Data. Também presumimos que você saiba programar em C#.
Visão geral do modelo de dados
A biblioteca de cliente C# oferece um conjunto de classes que correspondem aos elementos e tipos de dados usados pelas APIs Google Data. Por exemplo, há uma classe 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 Google Data têm uma classe própria. 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 uma entrada a um serviço, crie um objeto Feed ou Entry e chame um método de biblioteca (como o método insert) para traduzir automaticamente o objeto 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 é com uma biblioteca de terceiros adequada.
Assim como a sintaxe XML da API Google Data é extensível, o modelo de objeto correspondente também é. Por exemplo, a biblioteca de cliente fornece classes correspondentes aos elementos definidos no namespace Google Data.
Tutorial e exemplos
Os exemplos a seguir mostram como enviar várias solicitações do GData usando a biblioteca de cliente C#.
Para torná-los mais concretos, esses exemplos mostram como interagir com um serviço específico: o Google Agenda. Vamos destacar os pontos em que a Agenda difere 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 Google Agenda, consulte a documentação da API de dados do Google Agenda.
Criar e executar o cliente
Para compilar os exemplos neste documento, use a seguinte instrução "using":
using Google.GData.Client;
Como pedir um feed
Conforme descrito na documentação da API Google Calendar Data, é possível solicitar um feed do Google Agenda enviando a seguinte solicitação HTTP para o Google Agenda:
GET http://www.google.com/calendar/feeds/userID/private/full
Substitua userID pelo endereço de e-mail do usuário. Consulte o documento do Google Agenda para mais detalhes. Em vez disso, você pode usar o URL padrão especial para interagir com o Google Agenda (conforme descrito no documento do Google Agenda), mas, neste documento, vamos usar o URL do feed completo particular, que contém o ID do usuário.
Você também precisa fornecer a autenticação adequada. O sistema de autenticação que estamos usando aqui (conhecido como "Autenticação do Google para aplicativos instalados") é adequado apenas para uso em aplicativos cliente instalados, como clientes de computador, e 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 da Agenda usando a biblioteca de cliente C#, para um usuário com o endereço de e-mail "jo@gmail.com" e a senha "mypassword", use o seguinte 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);A classe Service representa uma conexão de cliente (com autenticação) a um serviço do GData. O procedimento geral para enviar uma consulta a um serviço usando a biblioteca de cliente consiste nas seguintes etapas:
- Obtenha ou crie o URL adequado.
- Se você estiver enviando dados para um serviço (por exemplo, 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ê estiver apenas solicitando um feed, como fazemos neste exemplo.
- Crie uma instância
Service, definindo o nome do serviço (como"cl"para o Google Agenda) e o nome do aplicativo (no formatocompanyName-applicationName-versionID). - Defina as credenciais apropriadas.
- Chame um método para enviar a solicitação e receber os resultados.
O método service.setUserCredentials define a propriedade service.Credentials com um objeto de credenciais de rede .NET padrão.
As credenciais são definidas como o ID e a senha do usuário em nome de quem 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 outros sistemas de autenticação, consulte a documentação Autenticação da Conta do Google.
Para solicitar um feed inteiro, chame o método service.Query, que usa um objeto FeedQuery e retorna todo o feed encontrado nesse URL. Vamos mostrar como enviar consultas mais específicas mais adiante neste documento.
Assim como outros métodos da classe Service, Query processa a autenticação e os redirecionamentos conforme necessário.
Inserir um novo item
Para inserir um item em um feed do Google Agenda, use o código a seguir:
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);Depois de definir o URL, construímos um objeto AtomEntry.
O título da entrada é um AtomTextConstruct, uma classe que contém texto de várias formas (texto simples, HTML ou XHTML). O conteúdo da entrada é representado por um objeto AtomContent, uma classe que pode conter texto simples ou outras formas de conteúdo, incluindo XML e dados binários.
Cada autor é representado como um nome, um URI e um endereço de e-mail. Neste exemplo, vamos omitir o URI. Para adicionar um autor a uma entrada, adicione um objeto AtomAuthor à coleção Authors da entrada.
Estamos usando o mesmo objeto Service 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 outros elementos gerados pelo servidor, como um URL de edição para a entrada.
O código acima é equivalente a enviar POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (com autenticação adequada) e fornecer uma entrada.
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, não é necessário recuperar essa entrada, porque o Google Agenda já retornou a entrada inserida. No entanto, a mesma técnica pode ser aplicada sempre que você souber o URL de uma entrada.
FeedQuery singleQuery = new FeedQuery(); singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); AtomFeed newFeed = service.Query(singleQuery); AtomEntry retrievedEntry = newFeed.Entries[0];
A entrada inserida tem uma propriedade, SelfUri, que retorna um objeto AtomUri. Usando o método ToString() dele, é possível criar um novo objeto URI.
Em seguida, basta chamar o método Query do serviço para receber um novo objeto AtomFeed, com apenas uma entrada na coleção "Entries".
O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID para o Google Agenda com a autenticação adequada.
Pesquisar uma entrada
Para recuperar a primeira correspondência em uma pesquisa de texto completo, use o seguinte 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 exemplo começa construindo um objeto FeedQuery, que consiste principalmente em um URL mais parâmetros de consulta associados. Cada um dos parâmetros de consulta padrão do GData tem uma propriedade.
Depois de construir o FeedQuery, transmitimos ele ao método Query do serviço, que retorna um feed com os resultados da consulta. Uma abordagem alternativa seria construir um URL por conta própria (anexando parâmetros de consulta ao URL do feed) e chamar o método Query. No entanto, o método FeedQuery oferece uma camada útil de abstração para que você não precise construir o URL por conta própria.
A coleção Entries do feed retorna uma lista das entradas no feed. Entries.Count retorna o número de entradas no feed.
Nesse caso, se a consulta retornar algum resultado, vamos atribuir o primeiro resultado correspondente a um objeto AtomEntry. Em seguida, usamos a propriedade Title da classe AtomEntry para recuperar o título da entrada.
O código acima é equivalente a enviar GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis para a Agenda.
Consultar por categoria
Observação: o Google Agenda não associa rótulos a eventos. Portanto, este exemplo não funciona com o Agenda.
Para recuperar um feed com todas as entradas que correspondem à pesquisa de texto completo anterior e que estão em uma categoria específica ou têm um marcador específico, use o seguinte código:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);A classe AtomCategory, é claro, representa uma categoria a ser usada em um filtro de categoria. A classe QueryCategory pode conter várias categorias, mas, neste caso, estamos criando um filtro com apenas uma categoria.
Em seguida, adicionamos esse filtro à consulta atual, 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 permitisse uma pesquisa por categoria, o código acima seria equivalente ao envio de GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis para o Google Agenda.
Atualizar um item
Para atualizar um item, use o seguinte código. No exemplo a seguir, vamos mudar o título da entrada recuperada anteriormente do texto antigo ("Tennis with Beth") para "Important meeting".
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Primeiro, definimos um novo título para a entrada que buscamos anteriormente. Em seguida, basta chamar o método Upate para enviar a entrada atualizada ao serviço.
O serviço retorna a entrada atualizada, incluindo um novo URL para a nova versão dela. Para mais informações sobre versões de entrada, consulte a seção Simultaneidade otimista do documento de referência do protocolo v1.
O código acima é aproximadamente equivalente ao envio de PUT http://www.google.com/calendar/feeds/jo@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 um item, use o seguinte código:
updateEntry.Delete();
O URL usado para exclusão é o mesmo do URL de edição. Portanto, este exemplo é muito semelhante ao anterior, exceto que 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/jo@gmail.com/private/full/entryID ao serviço.
Trabalhar com feeds do Google Agenda
Os exemplos acima mostram como usar a API Google Data C# para trabalhar com feeds GData genéricos. No entanto, quando você trabalha com um feed do Google Agenda, ele contém muitos dados específicos do calendário que não são facilmente acessíveis usando os objetos padrão orientados a Atom na biblioteca de API básica. Para ajudar você a interagir com esses feeds, oferecemos as seguintes extensões:
using Google.GData.Extensions; using Google.GData.Calendar;
O namespace Extensions lida com extensões em geral. O namespace Calendar dá acesso a um serviço de agenda, feed e objeto de consulta personalizados. Você pode encontrar um exemplo mais elaborado de como essas extensões são usadas no subdiretório /Samples da instalação da API C#. Os seguintes objetos são adicionados:
- EventQuery
- Uma subclasse de FeedQuery, que permite definir dois parâmetros personalizados para o serviço de Agenda (start-min e start-max).
- CalendarService
- Uma subclasse de serviço que pode retornar um feed de eventos.
- EventFeed
- Uma subclasse de AtomFeed que expõe EventEntries.
- EventEntry
- Uma subclasse de AtomEntry, que tem propriedades adicionais relacionadas a dados de agenda.
Para mais detalhes sobre essas classes especiais, consulte a documentação da API e o programa de amostras.
Referência
Para informações de referência sobre a biblioteca de cliente C#, consulte a documentação de referência.