אזהרה: דף זה עוסק בממשקי API הישנים יותר של Google, בממשקי ה-API של נתוני Google, והוא רלוונטי רק לממשקי ה-API שרשומים בספריית ממשקי ה-API של נתוני Google, שרבים מהם הוחלפו בממשקי API חדשים יותר. למידע על API חדש ספציפי, עיינו במסמכי התיעוד של ה-API החדש. למידע על הרשאת בקשות באמצעות ממשק API חדש יותר, יש לעיין בקטע אימות והרשאה של חשבונות Google.
המאמר הזה עוסק ב-JSON כפי שנעשה בו שימוש ב-Google Data Protocol. למידע נוסף על הפרוטוקול, קראו את המדריך למפתחים.
תוכלו להשתמש ב-JSON עם כל שפת תכנות, אבל הדוגמאות במסמך הזה הן ב-JavaScript.
מידע על פידים של JSON ופידים של XML
שירות של Google Data יוצר פיד בפורמט JSON על ידי המרה של פיד XML באמצעות הכללים הבאים:
Basic
- הפיד מיוצג כאובייקט JSON. כל רכיב או מאפיין מקננים מיוצגים כנכס שם/ערך של האובייקט.
- המאפיינים מומרים לנכסי מחרוזת.
- רכיבי צאצא מומרים למאפייני אובייקט.
- רכיבים שעשויים להופיע יותר מפעם אחת מומרים לערכי מערך.
- ערכי הטקסט של התגים מומרים למאפיינים
$t.
מרחב שמות
- אם לרכיב יש כינוי של מרחב שמות, הכינוי והרכיב משורשרים באמצעות "$". לדוגמה,
ns:elementהופך ל-ns$element.
XML
- גרסת ה-XML ומאפייני הקידוד מומרים למאפייני הגרסה והקידוד של רכיב הבסיס.
בדוגמה הבאה מוצגות גרסאות XML ו-JSON של אותו פיד. הם בכרטיסיות כדי לספק השוואה קלה.
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"}]},
}]
}
}
בקשת פידים מסוג JSON ושימוש בהם
Atom הוא פורמט ברירת המחדל של נתוני Google. אם לא מציינים פרמטר alt בבקשה, מקבלים פיד Atom.
הערה: נכון לעכשיו, ספריות הלקוח של נתוני Google לא תומכות ב-JSON.
פלט JSON
כדי לבקש תגובה בפורמט JSON, צריך להשתמש בפרמטר alt=json.
לדוגמה, כדי לבקש עדכון יומן של Google למפתחים בפורמט JSON, יש לשלוח את השאילתה הבאה:
http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json
פלט JSON-In-script
כדי לבקש תגובה שעוטפת JSON בקובץ תג של סקריפט, משתמשים בפרמטר alt=json-in-script ומוסיפים פונקציית קריאה חוזרת על ידי הוספת הפרמטר callback=functionName.
http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json-in-script&callback=myFunction
השימוש בפונקציות קריאה חוזרת מאפשר לך לעקוף חלק מבעיות האבטחה בדומיינים שונים שאתה עשוי להיתקל בהן ב-JavaScript טיפוסי בצד הלקוח. בדרך כלל דפדפנים מונעים ממך לטעון קבצים בדומיינים שונים, כיוון שיש בהם פרצות אבטחה שעלולות לגרום להתקפות בדומיינים.
פורמט JSON-in-script מאפשר לעקוף את ההגבלות האלה על-ידי טעינת התגובה בתג סקריפט בלקוח. כלומר, אפשר להשתמש בתגובה במקומות אחרים בקוד JavaScript בדף הזה. פלט ה-JSON נטען כאשר הדף נטען. אין צורך בטריקים נוספים.
זהו יישום פשוט שפועל למטה:
<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>
קטעים לדוגמה
בדף דוגמאות תמצאו דוגמאות לשימוש נכון ב-JSON עם Google Data APIs.
מקורות מידע נוספים
יש מספר משאבים חיצוניים שמומלץ לבדוק כדי לקבל מידע נוסף על JSON ועל השימוש בקובצי JSON באפליקציות אינטרנט.