Domande frequenti

    Panoramica

  1. Che cos'è un'API di dati di Google?
  2. Ho ricevuto una richiesta di funzionalità o una segnalazione di bug. Dove devo pubblicare?
  3. Dove posso porre una domanda su un'API specifica?
  4. Che cos'è JSON?
  5. Devo utilizzare XML? Sono disponibili altri formati di dati?
  6. Perché utilizzi REST?
  7. Hai qualche suggerimento o un breve codice campione per problemi comuni?
  8. Gmail ha un'API di dati?

    9. Autenticazione

  9. Qual è il nome del servizio in ClientLogin per ogni API di dati?
  10. Quando un utente si disconnette da un'applicazione, è necessario informare i server API?
  11. Un token di autenticazione ClientLogin ha una data di scadenza?
  12. Ho una domanda generica sugli Account Google. Dove devo andare?
  13. Come posso eseguire l'autenticazione in un'API?
  14. Quale valore devo utilizzare per il parametro di ambito AuthSub/OAuth 1?
  15. Esistono tipi diversi di token AuthSub? I token scadono?
  16. Qual è la differenza principale tra ClientLogin e AuthSub/OAuth 1?
  17. Posso utilizzare l'autenticazione ClientLogin in applicazioni web di terze parti?
  18. Che cos'è un CAPTCHA?
  19. Come faccio a generare una verifica CAPTCHA?
  20. Devo utilizzare ClientLogin nella mia applicazione web?
  21. Come faccio a trovare il nome utente quando utilizzo AuthSub/OAuth 1?
  22. Come faccio a utilizzare OAuth 1 con le librerie client dell'API di dati di Google?
  23. Come faccio a utilizzare AuthSub con le librerie client dell'API Google Data?
  24. Come faccio a utilizzare ClientLogin con le librerie client dell'API Google Data?

    25. Librerie client

  25. Quali linguaggi di programmazione supportano le librerie client di Google?
  26. Come faccio a segnalare un bug o una richiesta di funzionalità per una delle librerie client di dati di Google?
  27. Come faccio ad abilitare le opzioni di debug nelle librerie client?
  28. Dove posso trovare i documenti di riferimento per i corsi della libreria client?

    29. Risoluzione dei problemi

  29. Quali sono alcuni buoni strumenti per il debug HTTP?
  30. Come posso ricevere informazioni sui log HTTP nella libreria client Java?
  31. Come posso ricevere informazioni sui log HTTP nella libreria client .NET?
  32. Come faccio ad attivare la codifica gzip dai feed di dati di Google?
  33. Perché viene visualizzato un messaggio di errore "Impossibile connettersi a sslv2" quando si utilizza il client PHP?
  34. Come faccio a ottenere il documento di servizio Atom che descrive un feed?

Panoramica

Che cos'è un'API di dati di Google?

Un'API di dati di Google è un'API basata sul protocollo dei dati di Google. Il protocollo di dati di Google si basa sui formati di syndication Atom 1.0 e RSS 2.0, oltre all'APP (Atom Publishing Protocol).

Il protocollo Google Data estende questi standard in vari modi, utilizzando i meccanismi di estensione integrati negli standard. I feed sono conformi ai formati di distribuzione Atom o RSS. Il modello di pubblicazione è conforme al protocollo di pubblicazione Atom.

Il protocollo fornisce inoltre un modello generale per feed, query e risultati. Puoi utilizzarlo per inviare query e aggiornamenti a qualsiasi API di dati.

Ho una richiesta di funzionalità o una segnalazione di bug. Dove devo pubblicare?
Dai un'occhiata al nostro tracker dei problemi. Cerca la tua richiesta di funzionalità e aggiungila a Speciali per aggiungere l'assistenza e ricevere aggiornamenti sullo stato.
Dove devo fare una domanda su una particolare API?
Se il problema non è elencato qui o vuoi ricevere ulteriori chiarimenti, esistono gruppi di discussione specifici per ogni API di dati di Google:
Che cos'è JSON?

JSON indica JavaScript Object Notation.

JSON è un formato di interscambio di dati leggero la cui semplicità ha comportato un uso diffuso tra gli sviluppatori web. È facile da leggere e scrivere, puoi analizzarlo utilizzando qualsiasi linguaggio di programmazione e le sue strutture vengono mappate direttamente alle strutture di dati utilizzate nella maggior parte dei linguaggi di programmazione.

Scopri di più sull'utilizzo di JSON con le API di dati di Google.

Devo utilizzare XML? Sono disponibili altri formati di dati?
Il formato dei dati predefinito per le API di dati di Google è XML, sotto forma di feed di un Atom. Tuttavia, quando richiedi un feed, puoi specificare un formato alternativo utilizzando il parametro di ricerca alt.
  • alt=rss
    I dati delle risposte vengono formattati come feed RSS.
  • alt=json o alt=json-in-script
    restituisce una rappresentazione JSON della struttura XML del feed Atom. Il vantaggio di JSON è che è più facile "analizzare" il codice client JavaScript. Al momento l'utilizzo di JSON è disponibile solo come opzione di sola lettura. Tuttavia, l'utilizzo della libreria client JavaScript con i servizi Blogger, Contatti o Calendar consente di leggere e scrivere dati.

    Scopri di più su come richiedere e utilizzare i feed JSON.

  • alt=atom-in-script
    Simile a alt=json-in-script, ma i risultati vengono restituiti come stringa Atom XML anziché JSON.
  • alt=rss-in-script
    Simile a alt=atom-in-script, ma i risultati vengono restituiti come stringa XML RSS anziché come Atom.

Scopri di più sui formati alternativi nella Guida di riferimento dei dati di Google.

Perché utilizzi REST?
REST è semplice, leggero, scalabile e offre una mappatura ottimale per rappresentare ed esporre i dati.
Hai qualche suggerimento o un breve codice di esempio per problemi comuni?
Dai un'occhiata al blog dei suggerimenti dell'API di dati di Google per ricevere assistenza sia per le librerie client sia per le richieste non elaborate.
Gmail ha un'API di dati?

No, ma puoi utilizzare il feed Atom di Gmail con AuthSub o OAuth 1 per richiedere l'accesso di sola lettura ai messaggi da leggere di un utente. L'ambito deve essere impostato su https://mail.google.com/mail/feed/atom/. Esempio di query:

GET https://mail.google.com/mail/feed/atom/

Se ti interessa gestire la posta, Gmail offre anche il supporto IMAP/POP.

Autenticazione

Nella documentazione delle API di dati di Google, "OAuth" si riferisce a OAuth 1. Per i dettagli relativi a OAuth 2.0, consulta la documentazione della tua API.

Qual è il nome del servizio in ClientLogin per ogni API di dati?
Un "nome di servizio" è una breve stringa che il sistema di autenticazione ClientLogin utilizza per identificare un servizio Google.
API di Google Nome servizio
API di dati di Google Analytics analytics
API di G Suite
(Informazioni e gestione dominio)		 apps
API Google Sites Data jotspot
API Data di Blogger blogger
API Book Search Data print
API Data di Calendar cl
API Google Code Search Data codesearch
API Contacts Data cp
API Content per Shopping structuredcontent
API Documentazione elenco dati writely
API Finance Data finance
Feed Atom di Gmail mail
API Health Data health
weaver (sandbox H9)
API di dati di Maps local
API Data di Picasa Web Album lh2
API Data di Sidewiki annotateweb
API Fogli di lavoro Data wise
API Strumenti per i Webmaster sitemaps
API Data di YouTube youtube

Per ulteriori informazioni sugli altri parametri utilizzati in una richiesta ClientLogin, consultate la documentazione di ClientLogin.

Quando un utente si disconnette da un'applicazione, è necessario informare i server API?
No, non è necessario informare l'API Google Data quando un utente si disconnette da un'applicazione. Tuttavia, se la tua applicazione non deve più utilizzare un token AuthSub emesso, dovrebbe revocare il token.
Un token di autenticazione ClientLogin ha una data di scadenza?
Un token ClientLogin può durare fino a due settimane dalla data di emissione, ma il limite è specifico del servizio e può essere più breve.
Ho una domanda generica sugli Account Google. Dove posso andare?
Visita il Centro assistenza Google Account.
Come faccio ad autenticarmi a un'API?
La tua richiesta HTTP deve includere un'intestazione di autorizzazione che contiene un token ottenuto utilizzando ClientLogin, AuthSub o OAuth 1.
Quale valore devo utilizzare per il parametro di ambito AuthSub/Oauth 1?
Un parametro scope è richiesto da AuthSub e OAuth 1 per identificare i servizi Google a cui la tua applicazione avrà accesso. Per i dettagli relativi a OAuth 2.0, consulta la documentazione dell'API specifica.

API di Google Nome servizio ClientLogin
API Data di Google Analytics https://www.google.com/analytics/feeds/
API Google Sites Data http(s)://sites.google.com/feeds/
API Data di Blogger http://www.blogger.com/feeds/
API Book Search Data http://www.google.com/books/feeds/
API Data di Calendar http(s)://www.google.com/calendar/feeds/
API Contacts Data http(s)://www.google.com/m8/feeds/
API Content per Shopping https://www.googleapis.com/auth/structuredcontent
API Documentazione elenco dati http(s)://docs.google.com/feeds/
API Finance Data http://finance.google.com/finance/feeds/
Feed Atom di Gmail https://mail.google.com/mail/feed/atom/
API Health Data https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (sandbox H9)
API Maps Data http://maps.google.com/maps/feeds/
API Data di Picasa Web Album http://picasaweb.google.com/data/
API Portable Contacts http://www-opensocial.googleusercontent.com/api/people
API Data di Sidewiki http://www.google.com/sidewiki/feeds/
API Fogli di lavoro Data http(s)://spreadsheets.google.com/feeds/
API Strumenti per i Webmaster http://www.google.com/webmasters/tools/feeds/
API Data di YouTube http://gdata.youtube.com
Esistono diversi tipi di token AuthSub? I token scadono?
Esistono due tipi di token AuthSub. Il primo è un token monouso presentato alla tua applicazione web tramite il parametro di ricerca "token". Questo token scade la prima volta che viene utilizzato con il servizio per cui è stato emesso o quando viene scambiato con un token di sessione.

I token di sessione non scadono se non vengono revocati esplicitamente tramite l'utente o la chiamata all'API AuthSubRevokeToken. Un token monouso può essere scambiato con un token di sessione solo se l'URL originale di AuthSubRequest specificava session=1 come parametro di ricerca.
Qual è la differenza principale tra ClientLogin e AuthSub/OAuth 1?

AuthSub è progettato per le applicazioni web. Garantisce che le credenziali utente vengano inviate in modo sicuro direttamente dal browser web dell'utente ai server di Google, anziché tramite un sito web di terze parti.

ClientLogin è per le applicazioni desktop installate. Richiede all'applicazione richiedente di trasmettere le credenziali utente a Google per conto dell'utente.

Consulta la documentazione sull'API Google Account Authentication.

Posso utilizzare l'autenticazione ClientLogin in applicazioni web di terze parti?
L'utilizzo di ClientLogin in applicazioni web di terze parti è accettabile, ma fortemente sconsigliato. Come best practice, l'applicazione web non deve mai chiedere a un utente le proprie credenziali di accesso (potrebbe essere soggetto a snooping). Un'applicazione deve invece archiviare le credenziali utente lato server e avere un singolo "account di servizio", che viene sempre utilizzato per l'autenticazione con Google.
Che cos'è un CAPTCHA?
Un CAPTCHA (Completely Automated Public Turing test to Tell Computers and Humans Apart) è un tipo di test di risposta alle sfide utilizzato per determinare se l'utente è umano o meno. Il termine è un marchio registrato dalla Carnegie Mellon University. Visualizza ulteriori dettagli su Wikipedia. Abbiamo implementato CAPTCHA in ClientLogin.
Come posso generare una verifica CAPTCHA?
Viene utilizzato un algoritmo proprietario per determinare quando è richiesta una verifica CAPTCHA durante l'autenticazione. I ripetuti tentativi di autenticazione con credenziali errate spesso generano una verifica CAPTCHA.
Devo utilizzare ClientLogin nella mia applicazione web?
No. ClientLogin deve essere utilizzato dalle applicazioni installate su hardware di proprietà dell'utente. L'utilizzo dell'API ClientLogin nelle applicazioni web non è sicuro e altamente consigliato.
Come faccio a trovare il nome utente quando utilizzo AuthSub/OAuth 1?
Poiché ti viene fornito solo un token da Google che concede l'accesso ai feed dell'utente, potresti non sapere qual è il suo nome utente. Ciò può costituire un problema se l'URL del feed che vuoi utilizzare contiene il nome utente come parte del file. In questo caso, puoi utilizzare il nome utente speciale default per indicare "l'utente di cui sto utilizzando il token di autenticazione".
Come faccio a usare OAuth 1 con le librerie client dell'API di dati di Google?
Consulta l'articolo Utilizzo di OAuth 1 con le librerie client dell'API di dati di Google.
Come faccio a utilizzare AuthSub con le librerie client dell'API di dati di Google?
Leggi l'articolo Utilizzo di AuthSub con le librerie client dell'API di dati di Google.
Come faccio a utilizzare ClientLogin con le librerie client dell'API Google Data?
Consulta l'articolo Utilizzo di ClientLogin con le librerie client dell'API di dati Google.

Librerie client

Quali linguaggi di programmazione supportano le librerie client di Google?

Le librerie client di Java, .NET, Python e Objective-C sono ufficialmente supportate da Google. Inoltre, il nostro partner Zend ha scritto una libreria client di PHP. Utilizzando queste librerie, puoi creare richieste di protocollo dei dati Google, inviarle a un servizio ed elaborare le risposte del server. È inoltre disponibile una libreria client JavaScript che attualmente supporta solo Blogger, Calendar e Contatti Google.

Se scrivi una libreria client in un linguaggio diverso da Java, .Net, Python o Objective-C e vuoi condividere con la community di sviluppatori dell'API Data, pubblica un post nel gruppo di discussione delle API di dati di Google. Apprezziamo la tua opinione.

Come faccio a segnalare un bug o una richiesta di funzionalità per una delle librerie client?

È possibile segnalare bug o richieste di funzionalità per le librerie client nelle seguenti posizioni:

Dopo aver pubblicato il bug, crea un thread nel forum degli sviluppatori per l'API appropriata.

Come faccio ad abilitare le opzioni di debug nelle librerie client dell'API di dati di Google?
Leggi il seguente articolo per informazioni su come abilitare il debug con alcune librerie client: Debug dei client Google Data API: Esplorazione del traffico dall'interno del tuo programma
Dove posso trovare i documenti di riferimento per i corsi della libreria client?
Libreria client Guida di riferimento
Java Javadoc
JavaScript JSdoc.
.NET Doc
PHP Doc doc
Python Doc

Risoluzione dei problemi

Quali sono alcuni buoni strumenti per il debug HTTP?

Di seguito sono elencati diversi strumenti, ma puoi anche leggere l'articolo On the Wire: Network Capture Tools for API Developers, che descrive in modo approfondito sia WireShark che Navigator.

Squalo letale
Wireshark è un "analizzatore di protocollo di rete". Consente di acquisire il traffico di rete e analizzare i contenuti. È molto utile per eseguire il debug del traffico nelle librerie in cui non hai accesso diretto ai flussi di richieste e risposte HTTP. Il traffico tra l'applicazione e i servizi di autenticazione non può essere analizzato utilizzando Wireshark perché la comunicazione è criptata tramite SSL. Wireshark può essere utilizzato anche per analizzare il traffico acquisito utilizzando strumenti come tcpdump. Wireshark è a disposizione degli sviluppatori sia come codice sorgente sia come programma di installazione di Windows. Per molte piattaforme sono disponibili pacchetti di terze parti.
Autore
Navigator è un "proxy di debug HTTP". Se puoi configurare il tuo codice o l'ambiente di runtime in modo che utilizzi un server proxy per il traffico HTTP, Navigator si troverà tra l'applicazione e i servizi per i dati di Google in cui ti permetterà di ispezionare il traffico. Navigator 2 include il supporto per SSL. Navigator è attualmente disponibile solo per Windows.
URL
cURL è uno strumento a riga di comando che può eseguire richieste HTTP/HTTPS. È molto utile per testare rapidamente le interazioni con un servizio senza dover prima creare il supporto HTTP nel client.
Come posso ricevere informazioni sui log HTTP nella libreria client Java?

Le librerie client Java utilizzano il pacchetto java.util.logging per abilitare il logging delle richieste HTTP. Consente di attivare il logging delle intestazioni per le richieste e le risposte, nonché i codici di stato e gli URL delle richieste. Al momento non registra tutti i flussi di richieste e risposte. Il nome del logger utilizzato per questi log è com.google.gdata.client.http.HttpGDataRequest.

Nel caso in cui venga restituito un codice di errore dai server, viene generata un'eccezione. Le classi di eccezione ereditano da com.google.gdata.util.ServiceException e includono un metodo pubblico chiamato getResponseBody(). Consulta il Javadoc per ulteriori informazioni.

Come posso ricevere informazioni sui log HTTP nella libreria client .NET?
La libreria .NET utilizza i metodi di tracciamento System.Diagnostics per registrare il percorso di esecuzione, se il tracciamento è attivato. Inoltre, in caso di errore, viene visualizzato GDataRequestException. L'eccezione contiene un ResponseString che ti consente di accedere al corpo della risposta HTTP.
Come faccio ad attivare la codifica gzip dai feed di dati di Google?

Per ricevere una risposta con codifica gzip da una delle API di dati di Google, devi eseguire due operazioni: impostare un'intestazione "Accept-Encoding" e modificare il tuo user agent in modo che contenga la stringa "gzip". Esempio di intestazioni formattate correttamente:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Perché visualizzo l'errore "Impossibile connettersi a sslv2" quando utilizzo il client PHP?

A partire da luglio 2009, abbiamo iniziato a disattivare SSLv2 sui nostri server come misura precauzionale per migliorare la sicurezza. Sfortunatamente, è presente un bug nelle versioni precedenti della libreria client PHP rilasciate prima di luglio 2007 (versione 1.0.0 e precedenti) che obbliga le connessioni a utilizzare SSLv2. Quando ti connetti a un server in cui è disabilitata SSLv2, viene restituito il seguente errore:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

Per correggere questo errore, esegui l'upgrade a una release più recente della libreria client PHP, disponibile all'indirizzo http://framework.zend.com/download.

Se non riesci a eseguire l'upgrade a una release più recente, puoi risolvere il problema aggiungendo il seguente codice alla tua applicazione, dove $gdata è la tua istanza esistente di Zend_Gdata (o della sottoclasse appropriata):

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Come faccio a ottenere il documento di servizio Atom che descrive un feed?

Puoi ottenere il documento di servizio Atom passando il parametro alt=atom-service nella richiesta. Nota: solo la versione 2 delle API di dati di Google restituirà un documento di servizio conforme alla sintassi dei documenti di servizio AtomPub. La versione 1 delle API di dati di Google restituirà comunque un documento di servizio, ma si basa su una precedente specifica della bozza di AtomPub (sono presenti modifiche di sintassi e spazio dei nomi tra le due versioni).