استخدام 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 في تطبيقات الويب.

الرجوع إلى الأعلى