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.
Questo articolo illustra il formato JSON utilizzato all'interno del protocollo Google Data Protocol. Per scoprire di più sul protocollo, consulta la Guida per gli sviluppatori.
Puoi utilizzare JSON con qualsiasi linguaggio di programmazione, ma gli esempi in questo documento sono in JavaScript.
Informazioni sui feed JSON e XML
Un servizio dati Google crea un feed in formato JSON convertendo il feed XML in base alle seguenti regole:
Basic
- Il feed è rappresentato come un oggetto JSON; ogni elemento o attributo nidificato è rappresentato come una proprietà name/value dell'oggetto.
- Gli attributi vengono convertiti in proprietà di stringa.
- Gli elementi secondari vengono convertiti in proprietà dell'oggetto.
- Gli elementi che possono apparire più di una volta vengono convertiti in proprietà di array.
- I valori testuali dei tag vengono convertiti nelle proprietà
$t.
Spazio dei nomi
- Se un elemento ha un alias dello spazio dei nomi, l'alias e l'elemento vengono concatenati utilizzando "$". Ad esempio,
ns:elementdiventans$element.
XML
- La versione XML e gli attributi di codifica vengono convertiti rispettivamente in attributi di versione e codifica dell'elemento principale.
Nell'esempio seguente vengono mostrate le versioni XML e JSON dello stesso feed. Vengono visualizzate a schede per fornire un facile confronto.
XML
<?xml version="1.0" encoding="UTF-8" ?>
<feed xmlns="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/"
xmlns:gd="http://schemas.google.com/g/2005"
xmlns:gCal="http://schemas.google.com/gCal/2005">
<id>...</id>
<updated>2006-11-12T21:25:30.000Z</updated>
<title type="text">Google Developer Events</title>
<subtitle type="text">The calendar contains information about upcoming
developer conferences at which Google will be speaking, along with
other developer-related events.</subtitle>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml" href="..." />
<link rel="self" type="application/atom+xml" href="..." />
<author>
<name>Google Developer Calendar</name>
<email>developer-calendar@google.com</email>
</author>
<generator version="1.0"
uri="http://www.google.com/calendar">Google Calendar</generator>
<openSearch:startIndex>1</openSearch:startIndex>
<openSearch:itemsPerPage>25</openSearch:itemsPerPage>
<gCal:timezone value="America/Los_Angeles" />
<entry>
<id>...</id>
<published>2006-11-12T21:25:30.000Z</published>
<updated>2006-11-12T21:25:30.000Z</updated>
<category scheme="..." term="..." />
<title type="text">WebmasterWorld PubCon 2006:
Google Developer Tools in General</title>
<content type="text">Google is sponsoring at
<a href="http://www.pubcon.com/">WebmasterWorld PubCon 2006</a>. Come and
visit us at the booth or join us for an evening demo reception where we
will be talking "5 ways to enhance your website with Google Code".
After all, it is Vegas, baby! See you soon.</content>
<link rel="alternate" type="text/html" href="..." title="alternate" />
<link rel="self" type="application/atom+xml" href="..." />
<author>
<name>Google Developer Calendar</name>
<email>developer-calendar@google.com</email>
</author>
<gCal:sendEventNotifications value="true" />
<gd:comments>
<gd:feedLink href="..." />
</gd:comments>
<gd:transparency value="..." />
<gd:eventStatus value="..." />
<gd:where valueString="3150 Paradise Road, Las Vegas, NV 89109" />
<gd:when startTime="2006-11-15" endTime="2006-11-17">
<gd:reminder minutes="10" />
</gd:when>
</entry>
...
</feed>
JSON
{
"version": "1.0",
"encoding": "UTF-8",
"feed": {
"xmlns": "http://www.w3.org/2005/Atom",
"xmlns$openSearch": "http://a9.com/-/spec/opensearchrss/1.0/",
"xmlns$gd": "http://schemas.google.com/g/2005",
"xmlns$gCal": "http://schemas.google.com/gCal/2005",
"id": {"$t": "..."},
"updated": {"$t": "2006-11-12T21:25:30.000Z"},
"title": {
"type": "text",
"$t": "Google Developer Events"
},
"subtitle": {
"type": "text",
"$t": "The calendar contains information about upcoming developer
conferences at which Google will be speaking, along with other
developer-related events."
},
"link": [{
"rel": "...",
"type": "application/atom+xml",
"href": "..."
},{
"rel": "self",
"type": "application/atom+xml",
"href": "..."
}],
"author": [{
"name": {"$t": "Google Developer Calendar"},
"email": {"$t": "developer-calendar@google.com"}
}],
"generator":{
"version": "1.0",
"uri": "http://www.google.com/calendar",
"$t": "Google Calendar"
},
"openSearch$startIndex": {"$t": "1"},
"openSearch$itemsPerPage": {"$t": "25"},
"gCal$timezone": {"value": "America/Los_Angeles"},
"entry": [{
"id": {"$t": "..."},
"published": {"$t": "2006-11-12T21:25:30.000Z"},
"updated": {"$t": "2006-11-12T21:25:30.000Z"},
"category": [{
"scheme": "...",
"term": "..."
}],
"title":{
"type": "text",
"$t": "WebmasterWorld PubCon 2006: Google Developer Tools in General"
},
"content": {
"type": "text",
"$t": "Google is sponsoring at
<a href="http://www.pubcon.com/">WebmasterWorld PubCon 2006</a>.
\nCome and visit us at the booth or join us for an evening demo
reception where we will be talking "5 ways to enhance your website
with Google Code".\nAfter all,\nit is Vegas, baby! See you soon."
},
"link": [{
"rel": "alternate",
"type": "text/html",
"href": "...",
"title": "alternate"
},{
"rel": "self",
"type": "application/atom+xml",
"href": "..."
}],
"author": [{
"name": {"$t": "Google Developer Calendar"},
"email": {"$t": "developer-calendar@google.com"}
}],
"gd$transparency": {"value": "http://schemas.google.com/g/2005#event.opaque"},
"gd$eventStatus": {"value": "http://schemas.google.com/g/2005#event.confirmed"},
"gd$comments": {"gd$feedLink": {"href": "..."}},
"gCal$sendEventNotifications": {"value": "true"},
"gd$when": [{
"startTime": "2006-11-15",
"endTime": "2006-11-17",
"gd$reminder": [{"minutes": "10"}]
}],
"gd$where": [{"valueString": "3150 Paradise Road,Las Vegas,NV 89109"}]},
}]
}
}
Richiesta e utilizzo di feed JSON
Atom è il formato predefinito dei dati di Google. Se non specifichi un parametro alt nella richiesta, riceverai un feed Atom.
Nota: al momento, le librerie client dei dati di Google non supportano JSON.
Output JSON
Per richiedere una risposta in formato JSON, utilizza il parametro alt=json.
Ad esempio, per richiedere il feed del calendario dello sviluppatore di Google in formato JSON, invia la seguente query:
http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json
Output JSON nello script
Per richiedere una risposta che esegue il wrapping di JSON in un tag script, utilizza il parametro alt=json-in-script e aggiungi una funzione di callback aggiungendo il parametro callback=functionName.
http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json-in-script&callback=myFunction
L'utilizzo delle funzioni di callback consente di aggirare alcuni dei problemi di sicurezza tra domini che potresti incontrare in un tipico JavaScript lato client. In genere, i browser impediscono di caricare file tra domini a causa di potenziali problemi di sicurezza e attacchi che potrebbero verificarsi tra domini.
Il formato JSON in script consente di aggirare queste restrizioni caricando la risposta in un tag script sul client. Ciò significa che puoi utilizzare la risposta in altre posizioni del codice JavaScript di quella pagina. L'output JSON viene caricato al caricamento della pagina; non sono necessari altri suggerimenti.
La semplice applicazione di lavoro di seguito dimostra questa tecnica:
<h3>Upcoming Google Developer Events</h3>
<div id="agenda"></div>
<script>
function listEvents(root) {
var feed = root.feed;
var entries = feed.entry || [];
var html = ['<ul>'];
for (var i = 0; i < entries.length; ++i) {
var entry = entries[i];
var title = (entry.title.type == 'html') ? entry.title.$t : escape(entry.title.$t);
var start = (entry['gd$when']) ? entry['gd$when'][0].startTime : "";
html.push('<li>', start, ' ', title, '</li>');
}
html.push('</ul>');
document.getElementById("agenda").innerHTML = html.join("");
}
</script>
<script src="http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json-in-script&callback=listEvents">
</script>
Esempi
Per consultare esempi di utilizzo di JSON con le API di dati di Google, consulta la pagina degli esempi.
Risorse aggiuntive
Esistono diverse risorse esterne che ti consigliamo di consultare per ulteriori informazioni su JSON e sull'utilizzo di JSON nelle applicazioni web.