Este documento descreve como usar a biblioteca 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 os serviços ativados por GData, em diversas linguagens de programação. Usando essas bibliotecas, você pode criar solicitações GData, enviá-las para um serviço e receber respostas.
Este documento contém um conjunto de exemplos de usos comuns da versão C# da biblioteca de cliente, seguido por outras informações sobre como criar clientes de dados do Google. Ao 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 ambiente de execução do .NET 1.1, além de estar atualizado em todos os patches.
Faça o download da biblioteca de cliente .NET.
Os exemplos deste guia se referem à API Google Calendar, mas este não é um guia preciso ou atualizado para usar a API Calendar. Para saber como usar a biblioteca de cliente .NET com a API Data 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 de C# que desejam criar aplicativos clientes que possam interagir com serviços do GData.
Neste documento, presumimos que você entenda as ideias gerais por trás do protocolo das APIs de dados do Google. Você também precisa saber como programar em C#.
Visão geral do modelo de dados
A biblioteca de cliente C# fornece um conjunto de classes que correspondem aos elementos e tipos de dados 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 adequada.
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 dados do Google usando a biblioteca de cliente C#.
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, use a instrução a seguir:
using Google.GData.Client;
Como solicitar um feed
Conforme descrito na documentação da API Google Calendar 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. 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 C#, para um usuário com endereço de e-mail "jo@gmail.com" e 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) 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:
- Consiga ou construa o URL apropriado.
- 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.
- Crie uma nova instância
Service, definindo o nome do serviço (como"cl"para o 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 padrão da rede .NET.
As credenciais são definidas para 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 de Autenticação para aplicativos instalados. Para mais informações sobre outros sistemas de autenticação, consulte a documentação Autenticação de 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. Mais adiante neste documento, vamos mostrar como enviar consultas mais específicas.
Como outros métodos da classe Service, o Query processa a autenticação e os redirecionamentos conforme necessário.
Inserir um novo item
Para inserir um item em um feed do Agenda, use este 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);
Depois de definir o URL, criamos um objeto AtomEntry.
O título da entrada é uma AtomTextConstruct, uma classe que contém texto de várias formas (texto simples, HTML ou XHTML). O conteúdo de 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 nome, URI e endereço de e-mail. Neste exemplo, deixamos de fora 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 elementos adicionais 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.
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 dessa série de exemplos, recuperar essa entrada não é realmente necessário porque o Google Agenda já retornou a entrada inserida, mas 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 que, usando o método ToString(), pode ser usado para criar um novo objeto de URI.
Em seguida, precisamos chamar o método Query do serviço para receber um novo objeto AtomFeed, com apenas uma entrada na coleção de entradas.
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 autenticação correta.
Como 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;
}
Esse exemplo começa criando um objeto FeedQuery, que consiste principalmente em um URL e os parâmetros de consulta associados. Cada um dos parâmetros de consulta GData padrão tem uma propriedade.
Depois de construir o FeedQuery, 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 Query. No entanto, o método FeedQuery fornece uma camada útil de abstração para que você não precise criar o URL.
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 resultados, 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 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:
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 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/jo@gmail.com/private/full/-/by_jo?q=Tennis para o Google Agenda.
Como atualizar um item
Para atualizar um item existente, use o código a seguir. No exemplo a seguir, o título da entrada recuperada anteriormente é o texto antigo ("Tênis com Beth") para "Reunião importante".
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 desta entrada. 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 existente, use o código abaixo:
updateEntry.Delete();
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/jo@gmail.com/private/full/entryID ao serviço.
Trabalhar com os feeds do Google Agenda
Os exemplos acima descrevem como usar a API Google Data C# para trabalhar com feeds GData genéricos. No entanto, quando você está trabalhando com um feed do Google Agenda, ele contém muitos dados específicos da agenda que não podem ser acessados com facilidade usando os objetos Atom padrão na biblioteca de APIs de base. Para ajudar você a interagir com esses feeds, fornecemos as seguintes extensões:
using Google.GData.Extensions; using Google.GData.Calendar;
O namespace "Extensões" lida com extensões em geral. O namespace do Google Agenda fornece acesso a um serviço de agenda personalizado, a um feed e a um objeto de consulta. Veja 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:
- Consulta de evento
- Uma subclasse de FeedQuery, que permite definir dois parâmetros personalizados para o serviço do Agenda (start-min e start-max).
- Serviço de calendário
- Uma subclasse de serviço, que pode retornar um feed de eventos.
- Feed de eventos
- Uma subclasse do AtomFeed que expõe EventEntries.
- Entrada de evento
- Uma subclasse de AtomEntry, que tem propriedades adicionais relacionadas a dados da agenda.
Para mais detalhes sobre essas classes especiais, consulte a documentação da API e o programa de exemplos.
Referência
Para informações de referência sobre a biblioteca de cliente C#, consulte a documentação de referência.