Questo documento descrive come utilizzare la libreria client Java per inviare query all'API di dati Google ("GData") e interpretare le risposte restituite.
Google offre una serie di librerie client, in vari linguaggi di programmazione, per interagire con i servizi che hanno API di dati. Utilizzando queste librerie, puoi creare richieste GData, inviarle a un servizio e ricevere risposte.
Questo documento fornisce alcune informazioni generali sull'utilizzo della libreria client Java, insieme a una serie di esempi di usi comuni.
Per utilizzare questa libreria client, devi eseguire Java 1.5.
Scarica la libreria client Java.
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 Java 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 Java che vogliono 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 Java.
Per informazioni sulle classi e sui metodi forniti dalla libreria client, consulta la sezione Riferimento API della libreria client Java (in formato Javadoc).
Questo documento è progettato per essere letto in ordine; ogni esempio si basa su esempi precedenti.
Panoramica del modello di dati
La libreria client Java utilizza un insieme di classi per rappresentare gli elementi 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 manualmente. Il modo più semplice per farlo è tramite una libreria di terze parti appropriata come Rome.
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
I seguenti esempi mostrano come inviare varie richieste API di dati utilizzando la libreria client Java.
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, dovrai utilizzare le seguenti istruzioni di importazione:
import com.google.gdata.client.*; import com.google.gdata.client.calendar.*; import com.google.gdata.data.*; import com.google.gdata.data.extensions.*; import com.google.gdata.util.*; import java.net.URL;
Richiedere un feed
Come descritto nel documento Google Calendar Data API, 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. Le differenze principali tra questo esempio e il primo esempio nel documento di Calendar sono che (1) questo esempio include l'autenticazione e (2) questo esempio utilizza la classe GoogleService più generale invece della classe CalendarService specifica per Calendar.
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 Java, per un utente con indirizzo email "liz@gmail.com" e password "mypassword", utilizza il seguente codice:
// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");
// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());
// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);
La classe GoogleService 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
GoogleService, impostando il nome del servizio (ad esempio"cl"per Calendar) e il nome dell'applicazione (nel modulocompanyName-applicationName-versionID). - Imposta le credenziali appropriate.
- Indica alla libreria client quali estensioni verranno utilizzate dal feed, in modo che possa analizzare correttamente i feed restituiti.
- Chiama un metodo per inviare la richiesta e ricevere eventuali risultati.
Il metodo setUserCredentials specifica l'ID e la password dell'utente per conto del quale il client sta inviando la query. Gli esempi in questo documento utilizzano il sistema di autenticazione "Autenticazione per applicazioni installate". Per ulteriori informazioni sui sistemi di autenticazione, consulta la documentazione Autenticazione dell'Account Google.
Dopo aver impostato le credenziali, indichi le estensioni che verranno utilizzate dal feed chiamando il metodo declareExtensions. In questo caso, stiamo dicendo che il feed è un feed evento e pertanto utilizzerà le estensioni definite dal tipo di evento.
Per richiedere un intero feed, chiami il metodo getFeed, che accetta un URL e restituisce l'intero feed trovato in quell'URL. In seguito ti mostreremo come inviare query più specifiche.
Come altri metodi della classe GoogleService, getFeed gestisce l'autenticazione e i reindirizzamenti in base alle necessità.
Inserimento di un nuovo elemento
Per creare un nuovo evento del calendario, puoi utilizzare il seguente codice:
URL postUrl =
new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();
myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));
Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);
DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);
// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);
Dopo aver impostato l'URL, creiamo un oggetto EventEntry; EventEntry deriva dalla classe di base astratta BaseEntry, che è anche la classe padre della classe Entry, che rappresenta un elemento <atom:entry>.
La classe EventEntry rappresenta un tipo di evento; per saperne di più, consulta il documento dei tipi. Per servizi diversi da Calendar, puoi assegnare la voce restituita a un oggetto Entry anziché a un oggetto EventEntry.
Il titolo della voce è un TextConstruct, una classe che contiene testo in vari formati (testo normale, HTML o XHTML). I contenuti delle voci sono rappresentati da un oggetto Content, una classe che può contenere testo normale o altre forme di contenuti, tra cui XML e dati binari. Tuttavia, il metodo setContent può anche accettare TextConstruct.
Ogni autore è rappresentato da un nome, un URI e un indirizzo email. In questo esempio non viene inserito l'URI. Puoi aggiungere un autore a una voce chiamando il metodo getAuthors().add della voce.
Stiamo utilizzando lo stesso oggetto GoogleService 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.
I codici di stato HTTP vengono restituiti come eccezioni.
Il codice sopra riportato corrisponde all'invio di POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (con l'autenticazione appropriata) e all'invio di una voce nel tipo Evento.
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'URI di una voce.
URL entryUrl = new URL(insertedEntry.getSelfLink().getHref()); EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);
La voce inserita ha un metodo getSelfLink che restituisce un oggetto Link che include l'URL della voce. La classe Link ha un metodo getHref che restituisce l'URL come String, a partire dal quale possiamo creare un oggetto URL.
Dobbiamo quindi chiamare il metodo getEntry del servizio per ottenere la voce.
Consideriamo EventEntry.class come parametro per getEntry, il che indica che ci aspettiamo che il servizio restituisca un evento, anziché una semplice voce. Per i servizi diversi da Calendar, potresti passare solo Entry.class.
Il codice riportato sopra equivale a inviare GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID a Calendar, con l'autenticazione corretta.
Ricerca delle voci in corso...
Per recuperare la prima corrispondenza da una ricerca di testo completo, utilizza il seguente codice:
Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}
In questo esempio viene creato un oggetto Query, composto principalmente da un URL e da parametri di ricerca associati. Ciascuno dei parametri di ricerca GData standard ha un metodo del setter. Puoi anche impostare parametri di ricerca personalizzati per un determinato servizio, utilizzando il metodo addCustomParameter.
Dopo aver creato Query, 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 getFeed, ma il metodo query fornisce un livello utile di astrazione per evitare di costruire l'URL autonomamente.
Il metodo getEntries del feed restituisce un elenco di voci nel feed; getEntries().size restituisce il numero di voci nel feed.
In questo caso, se la query ha restituito risultati, assegniamo il primo risultato corrispondente a un oggetto Entry. Quindi utilizziamo il metodo getTitle().getPlainText della classe Entry per recuperare il titolo della voce e convertirla in testo.
Il codice precedente corrisponde a inviare GET http://www.google.com/calendar/feeds/liz@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:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);
La classe Category, naturalmente, rappresenta una categoria da utilizzare in un filtro di categoria. La classe Query.CategoryFilter 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/liz@gmail.com/private/full/-/by_liz?q=Tennis a Calendar.
Aggiornamento di un elemento
Per aggiornare un articolo esistente, utilizza il codice seguente. In questo esempio cambieremo il titolo della voce recuperata in precedenza dal suo vecchio testo ("Tennis con Darcy") a "Riunione importante".
retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);
Innanzitutto abbiamo impostato un nuovo titolo per la voce recuperata in precedenza. In seguito, riceviamo l'URL di modifica della voce tramite il metodo getEditLink. Quindi chiamiamo il metodo update del servizio per inviare la voce aggiornata.
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 Contemporaneità ottimistica del documento di riferimento del protocollo.
Il codice riportato sopra corrisponde all'invio di PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID al servizio, oltre alla nuova voce (in formato Atom) per sostituire la voce originale.
Eliminare un elemento
Per eliminare la voce aggiornata, utilizza il codice seguente:
URL deleteUrl = new URL(updatedEntry.getEditLink().getHref()); myService.delete(deleteUrl);
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/liz@gmail.com/private/full/entryID al servizio.
Riferimento
Per informazioni sulle classi e sui metodi forniti dalla libreria client, consulta la sezione Riferimento API della libreria client Java (in formato Javadoc).