Questo documento descrive come utilizzare la libreria client .NET per inviare query Google Data API ("GData") e interpretare le risposte restituite.

Google fornisce un insieme di librerie client per interagire con i servizi abilitati a GData in una serie di linguaggi di programmazione. Utilizzando queste librerie, puoi creare richieste GData, inviarle a un servizio e ricevere risposte.

Questo documento fornisce una serie di esempi di utilizzi comuni della versione C# della libreria client, seguiti da altre informazioni sulla scrittura di client GData. Alla fine di questo documento è presente un link alla documentazione di riferimento per la libreria client C#, in formato NDoc.

Per utilizzare questa libreria client, è necessario il runtime .NET 1.1 e devi anche avere installato tutte le patch.

Scarica la libreria client .NET.

Gli esempi di questa guida fanno riferimento all'API Google Calendar, ma questa guida non è una guida accurata o aggiornata all'utilizzo dell'API Calendar. Per informazioni sull'utilizzo della libreria client .NET con l'API Data di un servizio specifico, consulta la documentazione specifica del servizio. Ad esempio, se utilizzi Calendar, leggi la Guida per gli sviluppatori dell'API Calendar Data.

Sommario

Pubblico

Questo documento è destinato ai programmatori C# che vogliono scrivere applicazioni client in grado di interagire con i servizi GData.

Questo documento presuppone che tu comprenda le idee generali alla base del protocollo Google Data APIs. Si presume inoltre che tu sappia programmare in C#.

Panoramica del modello di dati

La libreria client C# fornisce un insieme di classi che corrispondono agli elementi e ai tipi di dati utilizzati dalle API Google Data. Ad esempio, esiste una classe Feed, che corrisponde all'elemento <atom:feed>; ha metodi per creare una voce, ottenere e impostare i valori di vari elementi secondari e così via. Esiste anche una classe Entry, che corrisponde all'elemento <atom:entry>. Non tutti gli elementi definiti nelle API Google Data hanno una propria classe. Per maggiori dettagli, consulta la documentazione di riferimento.

La libreria può analizzare automaticamente i contenuti Atom e inserire i valori degli elementi Atom negli oggetti appropriati. Ad esempio, il metodo getFeed recupera un feed, lo analizza e restituisce un oggetto Feed con i valori risultanti.

Per inviare un feed o una voce a un servizio, crea un oggetto Feed o Voce, quindi chiama un metodo della libreria (ad esempio il metodo insert) per tradurre automaticamente l'oggetto in XML e inviarlo.

Se preferisci, puoi analizzare e/o generare autonomamente XML; il modo più semplice per farlo è utilizzare una libreria di terze parti appropriata.

Proprio come la sintassi XML dell'API Google Data è estensibile, anche il modello a oggetti corrispondente è estensibile. Ad esempio, la libreria client fornisce classi corrispondenti agli elementi definiti nello spazio dei nomi Google Data.

Tutorial ed esempi

Gli esempi seguenti mostrano come inviare varie richieste GData utilizzando la libreria client C#.

Per renderli più concreti, questi esempi mostrano come interagire con un servizio specifico: Google Calendar. Indicheremo i punti in cui Calendar differisce da altri servizi Google per aiutarti ad adattare questi esempi per l'utilizzo con altri servizi. Per ulteriori informazioni su Calendar, consulta la documentazione dell'API Google Calendar Data.

Creazione ed esecuzione del client

Per compilare gli esempi in questo documento, devi utilizzare la seguente istruzione using:

using Google.GData.Client;

Richiedere un feed

Come descritto nella documentazione dell'API Google Calendar Data, puoi richiedere un feed di Calendar inviando la seguente richiesta HTTP a Calendar:

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

Naturalmente, devi sostituire userID con l'indirizzo email dell'utente. Per maggiori dettagli, consulta il documento di Calendar. Puoi invece utilizzare l'URL predefinito speciale per interagire con Calendar (come descritto nel documento Calendar), ma in questo documento utilizzeremo l'URL del feed completo privato, che contiene l'ID utente.

Devi anche fornire un'autenticazione appropriata. Tieni presente che il sistema di autenticazione che utilizziamo qui (noto come "Autenticazione Google per applicazioni installate") è appropriato solo per l'utilizzo in applicazioni client installate come i client desktop, non per l'utilizzo in applicazioni web. Per saperne di più sull'autenticazione, consulta la documentazione relativa all'autenticazione dell'account Google.

Per richiedere un feed di Calendar utilizzando la libreria client C#, per un utente con indirizzo email "jo@gmail.com" e password "mypassword", utilizza il seguente codice:

// 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);

La classe Service rappresenta una connessione client (con autenticazione) a un servizio GData. La procedura generale per inviare una query a un servizio utilizzando la libreria client prevede i seguenti passaggi:

1. Ottieni o crea l'URL appropriato.
2. Se invii dati a un servizio (ad esempio, se inserisci una nuova voce), trasforma i dati non elaborati in oggetti utilizzando le classi della libreria client. Questo passaggio non è applicabile se stai solo richiedendo un feed, come in questo esempio.
3. Crea una nuova istanza Service, impostando il nome del servizio (ad esempio "cl" per Calendar) e il nome dell'applicazione (nel formato companyName-applicationName-versionID).
4. Imposta le credenziali appropriate.
5. Chiama un metodo per inviare la richiesta e ricevere eventuali risultati.

Il metodo service.setUserCredentials imposta la proprietà service.Credentials con un oggetto credenziali di rete .NET standard. Le credenziali sono impostate sull'ID e sulla password dell'utente per conto del quale il client invia la query. Gli esempi in questo documento utilizzano il sistema di autenticazione "Autenticazione per le applicazioni installate". Per saperne di più sugli altri sistemi di autenticazione, consulta la documentazione relativa all'autenticazione dell'Account Google.

Per richiedere un intero feed, chiama il metodo service.Query, che accetta un oggetto FeedQuery e restituisce l'intero feed trovato all'URL. Più avanti in questo documento ti mostreremo come inviare query più specifiche.

Come altri metodi della classe Service, Query gestisce l'autenticazione e i reindirizzamenti in base alle necessità.

Inserimento di un nuovo elemento

Per inserire un elemento in un feed di Calendar, puoi utilizzare il seguente codice:

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);

Dopo aver impostato l'URL, creiamo un oggetto AtomEntry.

Il titolo della voce è un AtomTextConstruct, una classe che contiene testo in varie forme (testo normale, HTML o XHTML). I contenuti della voce sono rappresentati da un oggetto AtomContent, una classe che può contenere testo normale o altre forme di contenuti, inclusi dati XML e binari.

Ogni autore è rappresentato da un nome, un URI e un indirizzo email. In questo esempio, omettiamo l'URI. Per aggiungere un autore a una voce, aggiungi un oggetto AtomAuthor alla raccolta Authors della voce.

Utilizziamo lo stesso oggetto Service che abbiamo creato nell'esempio precedente. In questo caso, il metodo da chiamare è Insert, che invia un elemento all'URL di inserimento specificato.

Il servizio restituisce la voce appena creata, che potrebbe contenere elementi aggiuntivi generati dal server, ad esempio un URL di modifica per la voce.

Il codice precedente equivale all'invio di POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (con l'autenticazione corretta) e alla fornitura di una voce.

Richiedere una voce specifica

Il seguente codice ti consente di richiedere la voce specifica che hai inserito nell'esempio precedente.

Nel contesto di questa serie di esempi, il recupero di questa voce non è realmente necessario, perché Calendar ha già restituito la voce inserita. Tuttavia, la stessa tecnica può essere applicata ogni volta che conosci l'URL di una voce.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

La voce inserita ha una proprietà, SelfUri, che restituisce un oggetto AtomUri che, utilizzando il metodo ToString(), può essere utilizzato per creare un nuovo oggetto URI.

A questo punto, dobbiamo solo chiamare il metodo Query del servizio per ottenere un nuovo oggetto AtomFeed con una sola voce nella raccolta Entries.

Il codice precedente equivale all'invio di GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID a Calendar, con l'autenticazione corretta.

Cercare una voce

Per recuperare la prima corrispondenza in una ricerca a testo intero, utilizza il seguente codice:

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; 
}

Questo esempio inizia creando un oggetto FeedQuery, che consiste principalmente in un URL più i parametri di query associati. A ognuno dei parametri di query GData standard corrisponde una proprietà.

Dopo aver creato FeedQuery, lo passiamo al metodo Query del servizio, che restituisce un feed contenente i risultati della query. Un approccio alternativo consiste nel creare un URL (aggiungendo parametri di query all'URL del feed) e poi chiamare il metodo Query, ma il metodo FeedQuery fornisce un utile livello di astrazione in modo da non dover creare l'URL.

La raccolta Entries del feed restituisce un elenco delle voci del feed, mentre Entries.Count restituisce il numero di voci del feed.

In questo caso, se la query ha restituito risultati, assegniamo il primo risultato corrispondente a un oggetto AtomEntry. Poi utilizziamo la proprietà Title della classe AtomEntry per recuperare il titolo della voce.

Il codice riportato sopra equivale all'invio di GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis a Calendar.

Eseguire query per categoria

Nota: Google Calendar non associa le etichette agli eventi, quindi questo esempio non funziona con Calendar.

Per recuperare un feed composto da tutte le voci che corrispondono alla ricerca full-text precedente e che si trovano in una determinata categoria o hanno una determinata etichetta, utilizza il seguente codice:

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

La classe AtomCategory, ovviamente, rappresenta una categoria da utilizzare in un filtro per categoria. La classe QueryCategory può contenere più categorie, ma in questo caso stiamo creando un filtro con una sola categoria.

Aggiungiamo quindi questo filtro alla query esistente, che contiene ancora la stringa di query full-text dell'esempio precedente.

Utilizziamo di nuovo il metodo Query per inviare la query al servizio.

Se Calendar consentisse una ricerca per categoria, il codice precedente equivarrebbe all'invio di GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/-/by_jo?q=Tennis a Calendar.

Aggiornamento di un elemento

Per aggiornare un elemento esistente, utilizza il seguente codice. Nell'esempio seguente, modifichiamo il titolo della voce recuperata in precedenza dal testo precedente ("Tennis con Beth") a "Riunione importante".

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

Innanzitutto, impostiamo un nuovo titolo per la voce recuperata in precedenza. Quindi chiamiamo il metodo Upate per inviare la voce aggiornata al servizio.

Il servizio restituisce la voce aggiornata, incluso un nuovo URL per la nuova versione della voce. Per ulteriori informazioni sulle versioni delle voci, consulta la sezione Concurrency ottimistica del documento di riferimento del protocollo v1.

Il codice precedente equivale approssimativamente all'invio di PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servizio, insieme alla nuova voce (in formato Atom) per sostituire la voce originale.

Eliminazione di un elemento

Per eliminare un elemento esistente, utilizza il seguente codice:

updateEntry.Delete();

L'URL da utilizzare per l'eliminazione è lo stesso dell'URL di modifica, quindi questo esempio è molto simile al precedente, tranne ovviamente per il fatto che chiamiamo il metodo Delete anziché Update.

Il codice riportato sopra equivale approssimativamente all'invio di DELETE http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servizio.

Utilizzare i feed di Google Calendar

Gli esempi precedenti descrivono come utilizzare l'API Google Data C# per lavorare con i feed GData generici. Quando lavori con un feed di Google Calendar in particolare, tuttavia, il feed contiene molti dati specifici del calendario che non sono facilmente accessibili utilizzando gli oggetti standard orientati ad Atom nella libreria API di base. Per aiutarti a interagire con questi feed, forniamo le seguenti estensioni:

using Google.GData.Extensions;
using Google.GData.Calendar;

Lo spazio dei nomi Extensions si occupa delle estensioni in generale, mentre lo spazio dei nomi Calendar ti consente di accedere a un servizio di calendario, a un feed e a un oggetto di query personalizzati. Puoi trovare un esempio più elaborato di come vengono utilizzate queste estensioni nella sottodirectory /Samples dell'installazione dell'API C#. Vengono aggiunti i seguenti oggetti:

EventQuery

Una sottoclasse di FeedQuery, che consente di impostare due parametri personalizzati per il servizio Calendar (start-min e start-max).

CalendarService

Una sottoclasse di servizio, che può restituire un feed di eventi.

EventFeed

Una sottoclasse di AtomFeed, che espone EventEntries.

EventEntry

Una sottoclasse di AtomEntry, che ha proprietà aggiuntive relative ai dati del calendario.

Per ulteriori dettagli su queste classi speciali, consulta la documentazione dell'API e il programma di esempio.

Riferimento

Per informazioni di riferimento sulla libreria client C#, consulta la documentazione di riferimento.

Torna all'inizio