Panoramica della Guida per gli sviluppatori

Avviso: questa pagina riguarda le API di Google più vecchie, le API di dati di Google; è pertinente solo per le API elencate nella directory delle API di dati di Google, molte delle quali sono state sostituite con API più recenti. Per informazioni su una nuova API specifica, consulta la documentazione della nuova API. Per informazioni sulle autorizzazioni per le richieste con un'API più recente, vedi Autenticazione e autorizzazione degli Account Google.

La missione di Google è organizzare le informazioni a livello mondiale e renderle universalmente accessibili e fruibili. Ciò include rendere le informazioni accessibili in contesti diversi da un browser web e accessibili a servizi esterni a Google.

Google Data Protocol fornisce agli sviluppatori esterni un mezzo sicuro per scrivere nuove applicazioni che consentono agli utenti finali di accedere ai dati archiviati da molti prodotti Google e aggiornarli. Gli sviluppatori esterni possono utilizzare direttamente Google Data Protocol oppure qualsiasi linguaggio di programmazione supportato fornito dalle librerie client.

Pubblico

Questo insieme di documenti è pensato per chiunque voglia comprendere il protocollo dati di Google. Anche se vuoi solo scrivere codice che utilizza le librerie client specifiche per i vari linguaggi, questo set di documenti può essere utile se vuoi capire cosa succede sotto il livello di astrazione della libreria client.

Se stai cercando la Guida per gli sviluppatori per un'API specifica, visita la Directory API di Google Data Protocol.

Se vuoi accedere a un'API nel tuo linguaggio di programmazione preferito, visita la pagina di download delle librerie client.

Informazioni preliminari

Alcuni prodotti Google, come Calendar e Fogli di lavoro, forniscono API basate sul protocollo dati di Google. In qualità di sviluppatore, puoi utilizzare queste API per scrivere applicazioni client che offrono agli utenti finali nuovi modi per accedere e gestire i dati archiviati in tali prodotti Google.

Nota: a volte i prodotti Google che forniscono API vengono indicati come servizi in questi e in altri documenti correlati.

Se scrivi il codice che utilizza direttamente Google Data Protocol, accede all'API utilizzando richieste HTTP come GET o POST. Con queste richieste, i dati archiviati dal prodotto Google vengono trasferiti avanti e indietro sotto forma di feed di dati tramite cavo. I feed di dati sono semplicemente elenchi strutturati che contengono i dati. In passato, il formato del feed principale era AtomPub XML, ma ora è disponibile anche il formato JSON, o JavaScript Object Notation, come formato alternativo.

Se preferisci non scrivere codice che esige direttamente le richieste HTTP, puoi programmare la tua applicazione client utilizzando uno dei linguaggi di programmazione disponibili nell'insieme delle librerie client fornite. In questo modo, i dettagli delle richieste HTTP vengono gestiti dalla libreria client, scrivendo il tuo codice a un livello più concettuale utilizzando i metodi e le classi specifici della lingua forniti dalla libreria client.

Per ulteriori informazioni sulle lingue disponibili per l'API o la versione dell'API in uso, consulta la documentazione specifica del prodotto.

Versioni del protocollo

Protocollo versione 2.0 rispetto a protocollo versione 1.0

La prima versione del protocollo dati di Google è stata sviluppata prima della finalizzazione del protocollo di pubblicazione Atom. La seconda versione del protocollo Google Data Protocol è completamente conforme allo standard AtomPub RFC 5023.

Google Data Protocol versione 2.0 include anche il supporto per:

  • ETag HTTP. Uno standard web che consente alle applicazioni client di utilizzare meglio la memorizzazione nella cache HTTP. I servizi inclusi nelle librerie client che supportano il protocollo v2.0 gestiscono automaticamente i tag ETag.
  • Risposta parziale e Aggiornamento parziale (sperimentale). Funzionalità che ti consentono di effettuare richieste che trasferiscono meno dati. Richiedendo solo le informazioni che ti servono effettivamente o inviando aggiornamenti che includono solo i dati che vuoi effettivamente modificare, la tua applicazione client può risultare molto più efficiente nell'utilizzo di risorse di rete, CPU e memoria. Attualmente la risposta parziale e l'aggiornamento parziale sono disponibili soltanto per alcuni prodotti. Per scoprire se la tua API supporta questa funzionalità, consulta la documentazione specifica dei prodotti.

Aggiornamento dell'applicazione in corso...

Se l'API che stai utilizzando è stata basata sull'ultima versione del protocollo, la funzionalità Protocol v2.0 è inclusa nella relativa documentazione. In generale, consigliamo di eseguire l'upgrade dell'applicazione client alla versione più recente disponibile per l'API.

Aggiornamento di un client basato sulla libreria client

Se la tua applicazione client utilizza una libreria client, ad esempio la libreria client Java o la libreria client .NET, potrebbe contenere una versione dell'API che supporta le funzionalità Protocol v2.0. Per scoprirlo, consulta la documentazione dell'API del prodotto Google per sapere se entrambe le seguenti condizioni sono soddisfatte:

  • È disponibile una versione API che supporta le funzionalità di Google Data Protocol v2.0.
  • La libreria client che usi supporta anche la versione dell'API.

Se la libreria client lo supporta e vuoi aggiornare l'applicazione esistente, scarica e utilizza l'ultima versione della libreria client. Tutto il codice funziona ancora e la libreria client si occupa delle modifiche al protocollo v2.0.

Aggiornamento di un client HTTP non elaborato

Se hai scritto l'applicazione client direttamente utilizzando il protocollo Google Data Protocol, devi apportare le seguenti modifiche:

  • Richieste di versione non predefinite. Aggiungi un'intestazione della versione HTTP (GData-Version: X.0) a ogni richiesta HTTP che invii, dove X è la versione dell'API che supporta le funzionalità di Google Data Protocol v2.0. In alternativa, aggiungi un parametro di ricerca (v=X.0) all'URL di ogni richiesta, dove X è di nuovo la versione corretta dell'API. Se non specifichi una versione successiva, per impostazione predefinita le tue richieste vengono inviate alla versione più recente supportata dell'API.
  • Contemporaneità ottimistica. Se utilizzavi una versione di un'API che supportava la contemporaneità ottimistica, per utilizzare i tag ETag potrebbe essere necessario modificare l'aggiornamento ed eliminare il codice. Per ulteriori informazioni, leggi la sezione ETag della documentazione di riferimento di Google Data Protocol e leggi le sezioni Update ed Delete della guida per gli sviluppatori di Protocol per il servizio utilizzato dall'applicazione client.
  • Auto-modifica o URI. Se il tuo cliente tiene traccia di se stessi o modifica gli URI dei feed o delle voci, tieni presente che questi URI potrebbero essere cambiati. Per ottenere il nuovo URI, richiedi nuovamente l'elemento utilizzando l'URI precedente, ma contrassegna la richiesta come richiesta X.0, dove X è la versione dell'API che supporta le funzionalità di Google Data Protocol v2.0. Il server restituisce la nuova rappresentazione della voce, inclusi i nuovi URI, che puoi archiviare al posto di quelli precedenti.
  • URI dello spazio dei nomi. Se il client archivia gli URI dello spazio dei nomi dell'API Google Data Protocol localmente o ne ha uno hardcoded, dovrai aggiornarli:
    • Lo spazio dei nomi AtomPub (prefisso app) è stato modificato da http://purl.org/atom/app a http://www.w3.org/2007/app.
    • Lo spazio dei nomi OpenSearch (prefisso openSearch) è stato modificato da http://a9.com/-/spec/opensearchrss/1.0/ a http://a9.com/-/spec/opensearch/1.1/.