Questo documento descrive come utilizzare la libreria client .NET per inviare query sull'API di dati Google ("GData") e interpretare le risposte restituite.
Google offre una serie di librerie client per interagire con i servizi abilitati per GData in vari linguaggi di programmazione. Utilizzando queste librerie, puoi creare richieste GData, inviarle a un servizio e ricevere risposte.
Questo documento fornisce un insieme di esempi di usi 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, oltre a essere aggiornato su tutte le patch.
Scarica la libreria client .NET.
Gli esempi di questa guida si riferiscono all'API di Google Calendar, ma non rappresentano una guida accurata o aggiornata per l'utilizzo dell'API Calendar. Per informazioni sull'utilizzo della libreria client .NET con l'API di dati di un servizio specifico, consulta la documentazione specifica del servizio. Ad esempio, se utilizzi Calendar, leggi la Guida per gli sviluppatori dell'API Data Data di Calendar.
Sommario
Pubblico
Questo documento è destinato ai programmatori C# che desiderano scrivere applicazioni client che possono interagire con i servizi GData.
Questo documento presuppone che tu abbia un'idea generale del protocollo delle API di dati di Google, Presuppone inoltre che tu sappia come 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 di dati di Google. Ad esempio, c'è una classe Feed, che corrisponde all'elemento <atom:feed>, ha metodi per creare una voce, ottenere e impostare i valori dei vari elementi secondari e così via. C'è anche una classe Entry, che corrisponde all'elemento <atom:entry>. Non tutti gli elementi definiti nelle API di dati di Google hanno la propria classe. Per informazioni dettagliate, consulta la documentazione di riferimento.
La libreria può analizzare automaticamente i contenuti Atom e inserire i valori degli elementi Atom in oggetti appropriati. Ad esempio, il metodo getFeed riceve un feed, lo analizza e restituisce un oggetto Feed con i valori risultanti.
Per inviare un feed o una voce a un servizio, devi creare un oggetto Feed o Voce, quindi chiamare un metodo bibliotecario (come il metodo insert) per tradurre automaticamente l'oggetto in XML e inviarlo.
Se preferisci, puoi analizzare e/o generare XML autonomamente; il modo più semplice per farlo è tramite una libreria di terze parti appropriata.
Proprio come la sintassi XML dell'API di dati di Google è estensibile, il modello a oggetti corrispondente è estensibile. Ad esempio, la libreria client fornisce classi corrispondenti agli elementi definiti nello spazio dei nomi dei dati Google.
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 luoghi in cui Calendar è diverso 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 di dati di Google Calendar.
Creazione e gestione del client
Per compilare gli esempi in questo documento, devi utilizzare quanto segue utilizzando la dichiarazione:
using Google.GData.Client;
Richiedere un feed
Come descritto nella documentazione dell'API Google Data 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 i dettagli, consulta il documento di Calendar. In alternativa, puoi utilizzare l'URL speciale speciale per interagire con Calendar (come descritto nel documento Calendar), ma in questo documento utilizzeremo l'URL privato completo del feed, che contiene lo User-ID.
Inoltre, devi fornire l'autenticazione appropriata. Tieni presente che il sistema di autenticazione utilizzato qui (noto come "Autenticazione Google per le applicazioni installate") è appropriato solo per l'utilizzo in applicazioni client installate come client desktop, non per applicazioni web. Per ulteriori informazioni 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 l'invio di una query a un servizio mediante la libreria client è costituita dai seguenti passaggi:
- Ottenere o creare l'URL appropriato.
- Se invii dati a un servizio (ad esempio, se stai inserendo una nuova voce), trasforma i dati non elaborati in oggetti utilizzando le classi della libreria client. Questo passaggio non si applica se stai richiedendo solo un feed, come in questo esempio.
- Crea una nuova istanza
Service, impostando il nome del servizio (ad esempio"cl"per Calendar) e il nome dell'applicazione (nel modulocompanyName-applicationName-versionID). - Imposta le credenziali appropriate.
- 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 applicazioni installate". Per ulteriori informazioni sugli altri sistemi di autenticazione, consulta la documentazione relativa all'autenticazione dell'Account Google.
Per richiedere un intero feed, chiami il metodo service.Query, che accetta un oggetto FeedQuery e restituisce l'intero feed trovato in tale URL. In seguito 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 vari formati (testo normale, HTML o XHTML). I contenuti delle voci sono rappresentati da un oggetto AtomContent, una classe che può contenere testo normale o altre forme di contenuti, tra cui XML e dati binari.
Ogni autore è rappresentato da un nome, un URI e un indirizzo email. In questo esempio non viene inserito l'URI. Per aggiungere un autore a una voce, aggiungi un oggetto AtomAuthor alla raccolta Authors della voce.
Stiamo utilizzando 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 inserzione specificato.
Il servizio restituisce la voce appena creata, che potrebbe contenere altri elementi generati dal server, come un URL di modifica.
Il codice riportato sopra equivale a inviare POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (con l'autenticazione corretta) e a fornire una voce.
Richiedere una voce specifica
Il seguente codice consente di richiedere la voce specifica inserita nell'esempio precedente.
Nel contesto di questa serie di esempi, non è necessario recuperare la voce perché Calendar ha già restituito la voce inserita, ma 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, con il suo metodo ToString(), può essere utilizzato per creare un nuovo oggetto URI.
Dobbiamo quindi chiamare il metodo Query del servizio per ottenere un nuovo oggetto AtomFeed, con una sola voce nella raccolta delle voci.
Il codice riportato sopra equivale a inviare GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID a Calendar, con l'autenticazione corretta.
Ricerca di 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;
}
In questo esempio viene creato un oggetto FeedQuery, composto principalmente da un URL e da parametri di ricerca associati. Ciascuno dei parametri di ricerca GData standard ha una proprietà.
Dopo aver creato FeedQuery, lo trasmettiamo 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 ricerca all'URL del feed) e poi chiamare il metodo Query, ma il metodo FeedQuery fornisce un livello utile di astrazione per evitare di costruire l'URL autonomamente.
La raccolta Entries del feed restituisce un elenco di voci nel feed; Entries.Count restituisce il numero di voci nel feed.
In questo caso, se la query ha restituito risultati, assegniamo il primo risultato corrispondente a un oggetto AtomEntry. Quindi utilizziamo la proprietà Title della classe AtomEntry per recuperare il titolo della voce.
Il codice precedente corrisponde a inviare GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full?q=Tennis a Calendar.
Esecuzione di 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 precedente ricerca a testo intero 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, naturalmente, rappresenta una categoria da utilizzare in un filtro di categoria. La classe QueryCategory può contenere più categorie, ma in questo caso stiamo creando un filtro con una sola categoria.
In seguito, aggiungiamo questo filtro alla query esistente, che contiene ancora la stringa di query a testo intero dell'esempio precedente.
Usiamo di nuovo il metodo Query per inviare la query al servizio.
Se Calendar consentisse la ricerca per categoria, il codice sopra indicato equivale a inviare 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 articolo esistente, utilizza il codice seguente. Nell'esempio seguente stiamo modificando il titolo della voce recuperata in precedenza dal suo vecchio testo ("Tennis con Beth") a "Riunione importante".
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Innanzitutto abbiamo impostato un nuovo titolo per la voce recuperata in precedenza. Quindi, chiamiamo solo il metodo Upate per inviare la voce aggiornata al servizio.
Il servizio restituisce la voce aggiornata, incluso un nuovo URL per la nuova versione di questa voce. Per ulteriori informazioni sulle versioni delle voci, consulta la sezione sulla contemporaneità ottimistica del documento di riferimento del protocollo v1.
Il codice riportato sopra corrisponde all'invio di PUT http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID al servizio, oltre alla nuova voce (in formato Atom) per sostituire la voce originale.
Eliminare un elemento
Per eliminare un articolo esistente, utilizza il seguente codice:
updateEntry.Delete();
L'URL da utilizzare per l'eliminazione è uguale all'URL di modifica, pertanto questo esempio è molto simile al precedente, tranne per il fatto che stiamo chiamando il metodo Delete invece di Update.
Il codice riportato sopra corrisponde all'incirca 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 sopra riportati spiegano come utilizzare l'API Google Data C# per lavorare con feed GData generici. Quando lavori con un feed di Google Calendar in particolare, tuttavia, questo contiene molti dati specifici del calendario che non sono facilmente accessibili utilizzando gli oggetti standard orientati all'Atom nella libreria dell'API di base. Per aiutarti a interagire con tali feed, forniamo le seguenti estensioni:
using Google.GData.Extensions; using Google.GData.Calendar;
Lo spazio dei nomi delle estensioni gestisce in generale le estensioni; lo spazio dei nomi di Calendar ti consente di accedere a un servizio di calendario, un feed e un oggetto query personalizzati. Puoi trovare un esempio più elaborato di come vengono utilizzate tali estensioni nella sottodirectory /Samples dell'installazione dell'API C#. Vengono aggiunti i seguenti oggetti:
- Query evento
- Una sottoclasse di FeedQuery, che consente di impostare due parametri personalizzati per il servizio Calendar (start-min e start-max).
- Servizio di calendario
- Una classe secondaria del servizio, che può restituire un feed degli eventi.
- Feed evento
- Una sottoclasse di AtomFeed che espone le voci EventEntries.
- Ingresso evento
- Una sottoclasse di AtomEntry, che ha proprietà aggiuntive relative ai dati del calendario.
Per maggiori dettagli su questi corsi 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.