Domande frequenti

    Panoramica

  1. Che cos'è un'API Google Data?
  2. Ho una richiesta di funzionalità o una segnalazione di bug. Dove devo pubblicare?
  3. Dove posso fare una domanda su una determinata API?
  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 esempio di codice per problemi comuni?
  8. Gmail ha un'API Data?
  9. Autenticazione

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

  27. Quali linguaggi di programmazione hanno librerie client supportate da Google?
  28. Come faccio a segnalare un bug o una richiesta di funzionalità per una delle librerie client Google Data?
  29. Come faccio ad attivare le opzioni di debug nelle librerie client?
  30. Dove posso trovare i documenti di riferimento per le classi della libreria client?
  31. Risoluzione dei problemi

  32. Quali sono alcuni strumenti utili per il debug HTTP?
  33. Come faccio a ottenere informazioni di logging HTTP nella libreria client Java?
  34. Come faccio a ottenere informazioni di logging HTTP nella libreria client .NET?
  35. Come faccio ad attivare la codifica gzip dai feed di dati di Google?
  36. Perché visualizzo l'errore "Unable to Connect to sslv2" quando utilizzo il client PHP?
  37. Come faccio a ottenere il documento di servizio Atom che descrive un feed?

Panoramica

Che cos'è un'API Google Data?

Un'API Google Data è un'API basata sul protocollo Google Data. Il protocollo Google Data si basa sui formati di syndication Atom 1.0 e RSS 2.0, oltre al protocollo di pubblicazione Atom (APP).

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 syndication Atom o RSS. Il modello di pubblicazione è conforme al protocollo Atom Publishing.

Il protocollo fornisce anche un modello generale per feed, query e risultati. Puoi utilizzarla per inviare query e aggiornamenti a qualsiasi API Data.

Ho una richiesta di funzionalità o una segnalazione di bug. Dove devo pubblicare?
Consulta il nostro strumento Issue Tracker. Cerca la tua richiesta di funzionalità e aggiungi una stella per supportarla e ricevere aggiornamenti sul suo stato.
Dove posso porre una domanda su una determinata API?
Se il tuo problema non è elencato qui o vuoi ulteriori chiarimenti, esistono gruppi di discussione specifici per ogni API Google Data:
Che cos'è JSON?

JSON sta per JavaScript Object Notation.

JSON è un formato di scambio dati leggero la cui semplicità ha portato a un uso diffuso tra gli sviluppatori web. È facile da leggere e scrivere; puoi analizzarlo utilizzando qualsiasi linguaggio di programmazione e le sue strutture corrispondono 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 dati predefinito per le API Google Data è XML, sotto forma di feed Atom. Tuttavia, quando richiedi un feed puoi specificare un formato alternativo utilizzando il parametro di query alt.
  • alt=rss
    I dati di risposta sono formattati come feed RSS.
  • alt=json o alt=json-in-script
    Restituisce una rappresentazione JSON della struttura XML del feed Atom. Il vantaggio aggiuntivo di JSON è che è più facile da "analizzare" nel 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 sia la lettura che la scrittura dei 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 XML Atom anziché JSON.
  • alt=rss-in-script
    Simile a alt=atom-in-script, ma i risultati vengono restituiti come stringa XML RSS anziché Atom.

Scopri di più sui formati alternativi nella guida di riferimento ai dati di Google.

Perché utilizzi REST?
REST è semplice, leggero, scalabile e si adatta molto bene alla rappresentazione e all'esposizione dei dati.
Hai suggerimenti o brevi codici di esempio per problemi comuni?
Consulta il blog Suggerimenti per l'API di dati di Google per assistenza con le nostre librerie client e per effettuare richieste non elaborate.
Gmail ha un'API Data?

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

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

Se ti interessa gestire la posta, Gmail supporta anche IMAP/POP.


Autenticazione

Nella documentazione delle API di Google Data, "OAuth" si riferisce a OAuth 1; per i dettagli su OAuth 2.0, consulta la documentazione della singola API.

Qual è il nome del servizio in ClientLogin per ogni API Data?
Un "nome 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 G Suite
(informazioni e gestione del dominio)
apps
API Google Sites Data jotspot
API Blogger Data blogger
API Book Search Data print
API Calendar Data cl
API Google Code Search Data codesearch
API Contacts Data cp
API Content per Shopping structuredcontent
API Documents List Data writely
API Finance Data finance
Feed Atom di Gmail mail
API Health Data health
weaver (sandbox H9)
API Maps Data local
API Picasa Web Albums Data lh2
API Sidewiki Data annotateweb
API Spreadsheets Data wise
API Webmaster Tools sitemaps
API Data di YouTube youtube

Per saperne di più sugli altri parametri utilizzati in una richiesta ClientLogin, consulta la documentazione di ClientLogin.

Quando un utente esce da un'applicazione, è necessario informare i server API?
No, non è necessario informare l'API Google Data quando un utente esce da un'applicazione. Tuttavia, se la tua applicazione non ha più bisogno di utilizzare un token AuthSub emesso, deve revocare il token.
Un token di autenticazione ClientLogin ha una data di scadenza?
Un token ClientLogin può durare 2 settimane dalla data di emissione, ma questo limite è specifico per il servizio e può essere inferiore.
Ho una domanda generica sugli Account Google. Dove dovrei andare?
Visita il Centro assistenza Account Google.
Come faccio ad autenticarmi in un'API?
La richiesta HTTP deve includere un'intestazione Authorization 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 a quali servizi Google avrà accesso la tua applicazione. Per i dettagli su OAuth 2.0, consulta la documentazione della tua API specifica.

API di Google Nome del servizio ClientLogin
API di dati di Google Analytics https://www.google.com/analytics/feeds/
API Google Sites Data http(s)://sites.google.com/feeds/
API Blogger Data http://www.blogger.com/feeds/
API Book Search Data http://www.google.com/books/feeds/
API Calendar Data 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 Documents List Data 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 Picasa Web Albums Data http://picasaweb.google.com/data/
API Portable Contacts http://www-opensocial.googleusercontent.com/api/people
API Sidewiki Data http://www.google.com/sidewiki/feeds/
API Spreadsheets Data http(s)://spreadsheets.google.com/feeds/
API Webmaster Tools 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 che viene presentato alla tua applicazione web tramite il parametro di query "token". Questo token scade al primo utilizzo con il servizio per il quale è stato emesso o quando viene scambiato con un token di sessione.

I token di sessione non scadono a meno che non vengano revocati esplicitamente tramite l'utente o la chiamata API AuthSubRevokeToken. Un token monouso può essere scambiato con un token di sessione solo se l'URL AuthSubRequest originale ha specificato session=1 come parametro di query.
Qual è la principale differenza 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 di un 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 nelle applicazioni web di terze parti è accettabile, ma fortemente sconsigliato. Come best practice, l'applicazione web non deve mai chiedere a un utente le credenziali di accesso (potrebbe essere soggetta a spionaggio). Un'applicazione deve archiviare le credenziali dell'utente lato server e avere un singolo "service account" 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 Challenge/Response utilizzato per determinare se l'utente è umano. Il termine è un marchio registrato della Carnegie Mellon University. Scopri maggiori dettagli su Wikipedia. Abbiamo implementato CAPTCHA in ClientLogin.
Come faccio a generare una verifica CAPTCHA?
Un algoritmo proprietario viene utilizzato per determinare quando è necessaria una verifica CAPTCHA durante l'autenticazione. I tentativi di autenticazione ripetuti con credenziali errate spesso generano una verifica CAPTCHA.
Devo utilizzare ClientLogin nella mia applicazione web?
No, ClientLogin deve essere utilizzato dalle applicazioni installate sull'hardware di proprietà dell'utente. L'utilizzo dell'API ClientLogin nelle applicazioni web non è sicuro ed è fortemente sconsigliato.
Come faccio a trovare il nome utente dell'utente quando utilizzo AuthSub/OAuth 1?
Poiché ricevi solo un token da Google che concede l'accesso ai feed dell'utente, potresti non conoscere il suo nome utente. Questo può rappresentare un problema se l'URL del feed che vuoi utilizzare contiene il nome utente. 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 utilizzare OAuth 1 con le librerie client dell'API Google Data?
Consulta l'articolo Utilizzo di OAuth 1 con le librerie client dell'API Google Data.
Come faccio a utilizzare AuthSub con le librerie client dell'API Google Data?
Consulta l'articolo Utilizzo di AuthSub con le librerie client dell'API Google Data.
Come faccio a utilizzare ClientLogin con le librerie client dell'API Google Data?
Consulta l'articolo Utilizzo di ClientLogin con le librerie client delle API di Google Data.

Librerie client

Quali linguaggi di programmazione hanno librerie client supportate da Google?

Le librerie client Java, .NET, Python e Objective-C sono supportate ufficialmente da Google. Inoltre, il nostro partner Zend ha scritto una libreria client PHP. Utilizzando queste librerie, puoi creare richieste del protocollo Google Data, inviarle a un servizio ed elaborare le risposte del server. Esiste anche una libreria client JavaScript che al momento 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 condividerla con la community di sviluppatori di API Data, pubblica un post nel gruppo di discussione delle API Google Data. Ci piacerebbe conoscere la tua opinione.

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

I bug o le richieste di funzionalità per le librerie client possono essere segnalati nei seguenti siti:

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

Come faccio ad attivare le opzioni di debug nelle librerie client dell'API Google Data?
Per informazioni sull'attivazione del debug con alcune delle librerie client, consulta il seguente articolo: Debug dei client delle API di dati di Google: esplorare il traffico dall'interno del programma
Dove posso trovare i documenti di riferimento per le classi della libreria client?
Libreria client Guida di riferimento
Java Javadoc
JavaScript JSdoc
.NET NDoc
PHP phpDoc
Python PyDoc

Risoluzione dei problemi

Quali sono alcuni strumenti utili per il debug HTTP?

Di seguito sono elencati diversi strumenti, ma ti consigliamo anche di leggere l'articolo On the Wire: Network Capture Tools for API Developers, che descrive in dettaglio esempi di WireShark e Fiddler.

Wireshark
Wireshark è un "analizzatore di protocolli di rete". Consente di acquisire il traffico di rete e analizzare i contenuti. È molto utile per il debug del traffico che si verifica 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 utilizzando SSL. Wireshark può essere utilizzato anche per analizzare il traffico acquisito utilizzando strumenti come tcpdump. Wireshark è disponibile presso gli sviluppatori sia come codice sorgente che come programma di installazione per Windows. Sono disponibili pacchetti di terze parti per molte piattaforme.
Fiddler
Fiddler è un "proxy di debug HTTP". Se puoi configurare il tuo codice o l'ambiente di runtime in modo da utilizzare un server proxy per il traffico HTTP, Fiddler si troverà tra la tua applicazione e i servizi Google Data, dove ti consentirà di ispezionare il traffico. Fiddler 2 include il supporto di SSL. Fiddler è attualmente disponibile solo per Windows.
cURL
cURL è uno strumento da 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 faccio a ottenere informazioni sulla registrazione HTTP nella libreria client Java?

Le librerie client Java utilizzano il pacchetto java.util.logging per attivare la registrazione delle richieste HTTP. In questo modo potrai attivare la registrazione delle intestazioni per richieste e risposte, nonché dei codici di stato e degli URL delle richieste. Al momento non vengono registrati i flussi completi 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 eccezioni ereditano da com.google.gdata.util.ServiceException e includono un metodo pubblico chiamato getResponseBody(). Per ulteriori informazioni, consulta la Javadoc.

Come faccio a ottenere informazioni di logging HTTP nella libreria client .NET?
La libreria .NET utilizza i metodi di tracciamento System.Diagnostics per registrare il percorso di esecuzione, se il tracciamento è abilitato. Inoltre, in caso di errore, viene generato un 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 codificata con gzip da una delle API di dati di Google, devi fare due cose: impostare un'intestazione "Accept-Encoding" e modificare lo user agent in modo che contenga la stringa "gzip". Esempio di intestazioni formate correttamente:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Perché viene visualizzato 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. Purtroppo, nelle prime versioni della libreria client PHP rilasciate prima di luglio 2007 (versione 1.0.0 e precedenti) è presente un bug che impone alle connessioni di utilizzare SSLv2. Quando ti connetti a un server con SSLv2 disattivato, viene visualizzato 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 versione più recente della libreria client PHP, disponibile all'indirizzo http://framework.zend.com/download.

Se non riesci a eseguire l'upgrade a una versione più recente, puoi risolvere il problema aggiungendo il seguente codice all'applicazione, dove $gdata è l'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 Google Data restituirà un documento di servizio conforme alla sintassi del documento di servizio AtomPub. La versione 1 delle API Google Data restituirà comunque un documento di servizio, ma si basa su una bozza precedente della specifica AtomPub (ci sono modifiche alla sintassi e allo spazio dei nomi tra le due versioni).