استخدام JSON في بروتوكول بيانات Google
تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تحذير: تتعلق هذه الصفحة بواجهات برمجة التطبيقات القديمة من Google، وهي واجهات برمجة التطبيقات لبيانات Google؛ وهي مرتبطة فقط بواجهات برمجة التطبيقات المدرجة في دليل Google Data APIs، والتي تم استبدال العديد منها بواجهات برمجة تطبيقات أحدث. للحصول على معلومات حول واجهة برمجة تطبيقات جديدة، اطلع على وثائق واجهة برمجة التطبيقات الجديدة. للحصول على معلومات حول تفويض الطلبات باستخدام واجهة برمجة تطبيقات أحدث، اطلع على مصادقة حسابات Google وتفويضها.
تتناول هذه المقالة JSON أثناء استخدامه ضمن بروتوكول Google Data. لمزيد من المعلومات حول البروتوكول، يمكنك الاطلاع على دليل المطوِّر.
يمكنك استخدام JSON مع أي لغة برمجة، ولكن الأمثلة الواردة في هذا المستند تكون بلغة JavaScript.
لمحة عن خلاصات JSON وخلاصات XML
تنشئ خدمة بيانات Google خلاصة بتنسيق JSON عن طريق تحويل خلاصة XML باستخدام القواعد التالية:
أساسية
- يتم تمثيل الخلاصة ككائن 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-script-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
يتيح لك استخدام دوال الاستدعاء إمكانية التغلب على بعض مشكلات الأمان
التي قد تواجهها في جافا سكريبت النموذجية من جانب البرنامج والتي قد تواجهها عبر النطاقات. تمنعك المتصفحات عادةً من تحميل الملفات عبر النطاقات بسبب الثغرات الأمنية المحتمَلة والهجمات عبر النطاقات التي قد تنتج.
يسمح لك تنسيق JSON-in-script بالالتفاف حول هذه القيود عن طريق تحميل الاستجابة في علامة نص برمجي على البرنامج. وهذا يعني أنه يمكنك استخدام الاستجابة في أماكن أخرى في شفرة جافا سكريبت على تلك الصفحة.
يتم تحميل ناتج 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 في تطبيقات الويب.
الرجوع إلى الأعلى
إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0 ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.
تاريخ التعديل الأخير: 2023-03-01 (حسب التوقيت العالمي المتفَّق عليه)
[null,null,["تاريخ التعديل الأخير: 2023-03-01 (حسب التوقيت العالمي المتفَّق عليه)"],[[["\u003cp\u003eThis document explains how to use JSON with the older Google Data APIs to request and utilize data feeds.\u003c/p\u003e\n"],["\u003cp\u003eGoogle Data services can provide data in JSON format by converting XML feeds using specific rules for elements, attributes, and namespaces.\u003c/p\u003e\n"],["\u003cp\u003eTo request JSON output, use the \u003ccode\u003ealt=json\u003c/code\u003e parameter in your API request URL.\u003c/p\u003e\n"],["\u003cp\u003eFor JSON wrapped in a script tag (useful for cross-domain requests), use \u003ccode\u003ealt=json-in-script\u003c/code\u003e and a callback function with \u003ccode\u003ecallback=*functionName*\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eThe provided JavaScript example demonstrates fetching and displaying Google Calendar event data using JSON-in-script.\u003c/p\u003e\n"]]],[],null,["# Using JSON in the Google Data Protocol\n\n**Warning** : This page is about Google's older APIs, the Google Data APIs; it's relevant only to the APIs that are listed in the [Google Data APIs directory](/gdata/docs/directory), many of which have been replaced with newer APIs. For information about a specific new API, see the new API's documentation. For information about authorizing requests with a newer API, see [Google Accounts Authentication and Authorization](/accounts).\n\nThis article covers JSON as it is used within the Google Data Protocol. For more\ninformation about the protocol, view the [Developer's Guide](/gdata/docs/developers-guide).\n\nYou can use JSON with any programming language, but the examples in this document are in JavaScript.\n\nAbout JSON feeds and XML feeds\n==============================\n\nA Google Data service creates a JSON-format feed by converting the XML feed using the following rules:\n\n**Basic**\n\n- The feed is represented as a JSON object; each nested element or attribute is represented as a name/value property of the object.\n- Attributes are converted to String properties.\n- Child elements are converted to Object properties.\n- Elements that may appear more than once are converted to Array properties.\n- Text values of tags are converted to `$t` properties.\n\n**Namespace**\n\n- If an element has a namespace alias, the alias and element are concatenated using \"$\". For example, `ns:element` becomes `ns$element`.\n\n**XML**\n\n- XML version and encoding attributes are converted to version and encoding attributes of the root element, respectively.\n\nThe following example shows XML and JSON versions of the same feed. They are tabbed to provide easy comparison. \n\n### XML\n\n```\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003cfeed xmlns=\"http://www.w3.org/2005/Atom\"\n xmlns:openSearch=\"http://a9.com/-/spec/opensearchrss/1.0/\"\n xmlns:gd=\"http://schemas.google.com/g/2005\"\n xmlns:gCal=\"http://schemas.google.com/gCal/2005\"\u003e\n \u003cid\u003e...\u003c/id\u003e\n \u003cupdated\u003e2006-11-12T21:25:30.000Z\u003c/updated\u003e\n \u003ctitle type=\"text\"\u003eGoogle Developer Events\u003c/title\u003e\n \u003csubtitle type=\"text\"\u003eThe calendar contains information about upcoming\n developer conferences at which Google will be speaking, along with\n other developer-related events.\u003c/subtitle\u003e\n \u003clink rel=\"http://schemas.google.com/g/2005#feed\"\n type=\"application/atom+xml\" href=\"...\" /\u003e\n \u003clink rel=\"self\" type=\"application/atom+xml\" href=\"...\" /\u003e\n \u003cauthor\u003e\n \u003cname\u003eGoogle Developer Calendar\u003c/name\u003e\n \u003cemail\u003edeveloper-calendar@google.com\u003c/email\u003e\n \u003c/author\u003e\n \u003cgenerator version=\"1.0\"\n uri=\"http://www.google.com/calendar\"\u003eGoogle Calendar\u003c/generator\u003e\n \u003copenSearch:startIndex\u003e1\u003c/openSearch:startIndex\u003e\n \u003copenSearch:itemsPerPage\u003e25\u003c/openSearch:itemsPerPage\u003e\n \u003cgCal:timezone value=\"America/Los_Angeles\" /\u003e\n \n \u003centry\u003e\n \u003cid\u003e...\u003c/id\u003e\n \u003cpublished\u003e2006-11-12T21:25:30.000Z\u003c/published\u003e\n \u003cupdated\u003e2006-11-12T21:25:30.000Z\u003c/updated\u003e\n \u003ccategory scheme=\"...\" term=\"...\" /\u003e\n \u003ctitle type=\"text\"\u003eWebmasterWorld PubCon 2006:\n Google Developer Tools in General\u003c/title\u003e\n \u003ccontent type=\"text\"\u003eGoogle is sponsoring at \n \u003ca href=\"http://www.pubcon.com/\"\u003eWebmasterWorld PubCon 2006\u003c/a\u003e. Come and\n visit us at the booth or join us for an evening demo reception where we\n will be talking \"5 ways to enhance your website with Google Code\". \n After all, it is Vegas, baby! See you soon.\u003c/content\u003e\n \u003clink rel=\"alternate\" type=\"text/html\" href=\"...\" title=\"alternate\" /\u003e\n \u003clink rel=\"self\" type=\"application/atom+xml\" href=\"...\" /\u003e\n \u003cauthor\u003e\n \u003cname\u003eGoogle Developer Calendar\u003c/name\u003e\n \u003cemail\u003edeveloper-calendar@google.com\u003c/email\u003e\n \u003c/author\u003e\n \u003cgCal:sendEventNotifications value=\"true\" /\u003e\n \u003cgd:comments\u003e\n \u003cgd:feedLink href=\"...\" /\u003e\n \u003c/gd:comments\u003e\n \u003cgd:transparency value=\"...\" /\u003e\n \u003cgd:eventStatus value=\"...\" /\u003e\n \u003cgd:where valueString=\"3150 Paradise Road, Las Vegas, NV 89109\" /\u003e\n \u003cgd:when startTime=\"2006-11-15\" endTime=\"2006-11-17\"\u003e\n \u003cgd:reminder minutes=\"10\" /\u003e\n \u003c/gd:when\u003e\n \u003c/entry\u003e\n ...\n\u003c/feed\u003e\n \n```\n\n### JSON\n\n```\n{\n \"version\": \"1.0\",\n \"encoding\": \"UTF-8\",\n \"feed\": {\n \"xmlns\": \"http://www.w3.org/2005/Atom\",\n \"xmlns$openSearch\": \"http://a9.com/-/spec/opensearchrss/1.0/\",\n \"xmlns$gd\": \"http://schemas.google.com/g/2005\",\n \"xmlns$gCal\": \"http://schemas.google.com/gCal/2005\",\n \"id\": {\"$t\": \"...\"},\n \"updated\": {\"$t\": \"2006-11-12T21:25:30.000Z\"},\n \"title\": {\n \"type\": \"text\",\n \"$t\": \"Google Developer Events\"\n },\n \"subtitle\": {\n \"type\": \"text\",\n \"$t\": \"The calendar contains information about upcoming developer \n conferences at which Google will be speaking, along with other \n developer-related events.\"\n },\n \"link\": [{\n \"rel\": \"...\",\n \"type\": \"application/atom+xml\",\n \"href\": \"...\"\n },{\n \"rel\": \"self\",\n \"type\": \"application/atom+xml\",\n \"href\": \"...\"\n }],\n \"author\": [{\n \"name\": {\"$t\": \"Google Developer Calendar\"},\n \"email\": {\"$t\": \"developer-calendar@google.com\"}\n }],\n \"generator\":{\n \"version\": \"1.0\",\n \"uri\": \"http://www.google.com/calendar\",\n \"$t\": \"Google Calendar\"\n },\n \"openSearch$startIndex\": {\"$t\": \"1\"},\n \"openSearch$itemsPerPage\": {\"$t\": \"25\"},\n \"gCal$timezone\": {\"value\": \"America/Los_Angeles\"},\n\n \"entry\": [{\n \"id\": {\"$t\": \"...\"},\n \"published\": {\"$t\": \"2006-11-12T21:25:30.000Z\"},\n \"updated\": {\"$t\": \"2006-11-12T21:25:30.000Z\"},\n \"category\": [{\n \"scheme\": \"...\",\n \"term\": \"...\"\n }],\n \"title\":{\n \"type\": \"text\",\n \"$t\": \"WebmasterWorld PubCon 2006: Google Developer Tools in General\"\n },\n \"content\": {\n \"type\": \"text\",\n \"$t\": \"Google is sponsoring at\n \u003ca href=\"http://www.pubcon.com/\"\u003eWebmasterWorld PubCon 2006\u003c/a\u003e.\n \\nCome and visit us at the booth or join us for an evening demo\n reception where we will be talking \"5 ways to enhance your website\n with Google Code\".\\nAfter all,\\nit is Vegas, baby! See you soon.\"\n },\n \"link\": [{\n \"rel\": \"alternate\",\n \"type\": \"text/html\",\n \"href\": \"...\",\n \"title\": \"alternate\"\n },{\n \"rel\": \"self\",\n \"type\": \"application/atom+xml\",\n\t \"href\": \"...\"\n }],\n \"author\": [{\n \"name\": {\"$t\": \"Google Developer Calendar\"},\n \"email\": {\"$t\": \"developer-calendar@google.com\"}\n }],\n \"gd$transparency\": {\"value\": \"http://schemas.google.com/g/2005#event.opaque\"},\n \"gd$eventStatus\": {\"value\": \"http://schemas.google.com/g/2005#event.confirmed\"},\n \"gd$comments\": {\"gd$feedLink\": {\"href\": \"...\"}},\n \"gCal$sendEventNotifications\": {\"value\": \"true\"},\n \"gd$when\": [{\n \"startTime\": \"2006-11-15\",\n \"endTime\": \"2006-11-17\",\n \"gd$reminder\": [{\"minutes\": \"10\"}]\n }],\n \"gd$where\": [{\"valueString\": \"3150 Paradise Road,Las Vegas,NV 89109\"}]},\n }]\n }\n}\n```\n\nRequesting and using JSON feeds\n===============================\n\nAtom is Google Data's default format. If you don't specify an `alt` parameter in\nyour request, then you receive an Atom feed.\n\n**Note**: The Google Data client libraries don't currently support JSON.\n\n### JSON output\n\nTo request a response in JSON format, use the `alt=json` parameter.\n\nFor example, to request Google's developer calendar feed in JSON format, send the following query: \n\n```\nhttp://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json\n```\n\n### JSON-in-script output\n\nTo request a response that wraps JSON in a script tag, use the `alt=json-in-script`\nparameter and add a callback function by adding the `callback=`*functionName* parameter. \n\n```\nhttp://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json-in-script&callback=myFunction\n```\n\nUsing callback functions allows you get around some of the cross-domain\nsecurity issues you might encounter in typical client side JavaScript. Usually\nbrowsers prevent you from loading files across domains because of potential\nsecurity holes and the cross domain attacks that could result.\n\nThe JSON-in-script format allows you to get around these restrictions by\nloading the response in a script tag on the client. This means that you\ncan use the response in other places in your JavaScript code on that page.\nThe JSON output is loaded when the page is loaded; no other tricks are needed.\n\nThe simple working application below demonstrates this technique: \n\n```\n\u003ch3\u003eUpcoming Google Developer Events\u003c/h3\u003e\n\n\u003cdiv id=\"agenda\"\u003e\u003c/div\u003e\n\n\u003cscript\u003e\n function listEvents(root) {\n var feed = root.feed;\n var entries = feed.entry || [];\n var html = ['\u003cul\u003e'];\n\n for (var i = 0; i \u003c entries.length; ++i) {\n var entry = entries[i];\n var title = (entry.title.type == 'html') ? entry.title.$t : escape(entry.title.$t);\n var start = (entry['gd$when']) ? entry['gd$when'][0].startTime : \"\";\t\n\n html.push('\u003cli\u003e', start, ' ', title, '\u003c/li\u003e');\n }\n\n html.push('\u003c/ul\u003e');\n document.getElementById(\"agenda\").innerHTML = html.join(\"\");\n }\n\u003c/script\u003e\n\n\u003cscript src=\"http://www.google.com/calendar/feeds/developer-calendar@google.com/public/full?alt=json-in-script&callback=listEvents\"\u003e\n\u003c/script\u003e\n```\n\nSamples\n=======\n\nFor working examples of how to use JSON with the Google Data APIs, see the [samples](/gdata/samples) page.\n\nAdditional resources\n====================\n\nThere are several external resources that you may want to check out to learn more about JSON and using JSON in web applications.\n\n- [JSON.org](http://www.json.org/)\n- [Wikipedia entry on JSON](http://en.wikipedia.org/wiki/JSON)\n- [JSON: The Fat Free Alternative\n to XML](http://www.json.org/xml.html)\n\n[Back to top](#top)"]]
