مرجع پروتکل Google Data APIs

این سند پروتکل مورد استفاده توسط Google Data API را توصیف می کند، از جمله اطلاعاتی در مورد ظاهر یک پرس و جو، ظاهر نتایج و غیره.

برای اطلاعات بیشتر در مورد Google Data API، به سند راهنمای برنامه‌نویس داده‌های Google و راهنمای پروتکل مراجعه کنید.

حضار

این سند برای هر کسی در نظر گرفته شده است که می خواهد جزئیات قالب و پروتکل XML مورد استفاده توسط Google Data API را درک کند.

اگر فقط می خواهید کدی بنویسید که از API های سرویس گیرنده Google Data استفاده می کند، پس نیازی به دانستن این جزئیات ندارید. در عوض، می توانید از کتابخانه های مشتری خاص زبان استفاده کنید.

اما اگر می خواهید پروتکل را درک کنید، این سند را بخوانید. برای مثال، ممکن است بخواهید این سند را بخوانید تا در انجام هر یک از کارهای زیر به شما کمک کند:

  • ارزیابی معماری Google Data
  • کدگذاری با استفاده از پروتکل بدون استفاده از کتابخانه های سرویس گیرنده Google Data ارائه شده
  • نوشتن یک کتابخانه مشتری به زبان جدید

این سند فرض می‌کند که شما اصول XML، فضاهای نام، فیدهای اشتراکی، و درخواست‌های GET ، POST ، PUT ، و DELETE در HTTP و همچنین مفهوم HTTP از یک "منبع" را درک می‌کنید. برای اطلاعات بیشتر در مورد این موارد، به بخش منابع اضافی این سند مراجعه کنید.

این سند به هیچ زبان برنامه نویسی خاصی متکی نیست. شما می توانید پیام های Google Data را با استفاده از هر زبان برنامه نویسی که به شما امکان می دهد درخواست های HTTP و تجزیه پاسخ های مبتنی بر XML را ارسال و دریافت کنید.

جزئیات پروتکل

این بخش قالب سند Google Data و نحو پرس و جو را توضیح می دهد.

فرمت سند

Google Data، Atom، و RSS 2.0 همگی از یک مدل داده اولیه استفاده می کنند: محفظه ای که هم برخی از داده های جهانی و هم هر تعداد ورودی را در خود جای می دهد. برای هر پروتکل، قالب توسط یک طرحواره پایه تعریف می شود، اما می توان آن را با استفاده از فضاهای نام خارجی گسترش داد.

APIهای Google Data می‌توانند از فرمت Atom syndication (هم برای خواندن و هم برای نوشتن) یا فرمت RSS (فقط برای خواندن) استفاده کنند.

Atom قالب پیش فرض Google Data است. برای درخواست پاسخ در قالب RSS، از پارامتر /alt=rss/ استفاده کنید. برای اطلاعات بیشتر، به درخواست‌های درخواست مراجعه کنید.

وقتی داده‌هایی را در قالب RSS درخواست می‌کنید، Google Data یک فید (یا دیگر نمایش منبع) را در قالب RSS ارائه می‌کند. اگر ویژگی RSS معادلی برای یک ویژگی داده Google وجود نداشته باشد، Google Data از ویژگی Atom استفاده می‌کند و آن را با یک فضای نام مناسب برچسب‌گذاری می‌کند تا نشان دهد که پسوند RSS است.

توجه : اکثر فیدهای Google Data با فرمت Atom از فضای نام Atom به عنوان فضای نام پیش‌فرض با تعیین ویژگی xmlns در عنصر فید استفاده می‌کنند. برای نمونه هایی از نحوه انجام این کار، بخش مثال ها را ببینید. بنابراین، مثال‌های موجود در این سند به طور صریح atom: برای عناصر موجود در فید با فرمت Atom را مشخص نمی‌کنند.

جداول زیر نمایش Atom و RSS عناصر طرحواره را نشان می دهد. تمام داده هایی که در این جداول ذکر نشده اند به عنوان XML ساده در نظر گرفته می شوند و در هر دو نمایش یکسان نشان داده می شوند. مگر اینکه خلاف آن مشخص شده باشد، عناصر XML در یک ستون معین در فضای نام مربوط به آن ستون هستند. این خلاصه از نماد استاندارد XPath استفاده می کند: به ویژه، اسلش ها سلسله مراتب عنصر را نشان می دهند و علامت @ نشان دهنده ویژگی یک عنصر است.

در هر یک از جداول زیر موارد برجسته شده الزامی است.

جدول زیر عناصر یک فید Google Data را نشان می دهد:

مورد طرح خوراک نمایندگی اتم نمایندگی RSS
عنوان فید /feed/title /rss/channel/title
شناسه فید /feed/id /rss/channel/atom:id
پیوند HTML را تغذیه کنید /feed/link[@rel="alternate"] \
[@type="text/html"]/@href		 /rss/channel/link
شرح فید /feed/subtitle /rss/channel/description
زبان فید /feed/@xml:lang /rss/channel/language
حق نشر فید /feed/rights /rss/channel/copyright
نویسنده فید

/feed/author/name
/feed/author/email

(در موارد خاص لازم است؛ مشخصات Atom را ببینید.)

 /rss/channel/managingEditor
تاریخ آخرین به روز رسانی خوراک /feed/updated
(فرمت RFC 3339)		 /rss/channel/lastBuildDate
(فرمت RFC 822)
دسته خوراک /feed/category/@term /rss/channel/category
طرح طبقه بندی خوراک /feed/category/@scheme /rss/channel/category/@domain
مولد خوراک /feed/generator
/feed/generator/@uri		 /rss/channel/generator
نماد فید /feed/icon /rss/channel/image/url (مگر اینکه یک لوگو نیز وجود داشته باشد، در این صورت نماد در فید گنجانده نشده است)
آرم فید /feed/logo /rss/channel/image/url

جدول زیر عناصر یک فید نتایج جستجوی Google Data را نشان می دهد. توجه داشته باشید که Google Data برخی از عناصر OpenSearch 1.1 Response را در فیدهای نتایج جستجو نشان می دهد.

مورد طرح فید نتایج جستجو نمایندگی اتم نمایندگی RSS/OpenSearch
تعداد نتایج جستجو /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
فهرست شروع نتایج جستجو /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
تعداد نتایج جستجو در هر صفحه /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage

جدول زیر عناصر ورودی Google Data را نشان می دهد:

آیتم طرحواره ورودی نمایندگی اتم نمایندگی RSS
شناسه ورودی /feed/entry/id /rss/channel/item/guid
شناسه نسخه ورودی به صورت اختیاری در EditURI تعبیه شده است (به بخش همزمانی خوش بینانه این سند مراجعه کنید). -
عنوان ورودی /feed/entry/title /rss/channel/item/title
لینک ورود /feed/entry/link /rss/channel/item/link
/rss/channel/item/enclosure
/rss/channel/item/comments
خلاصه ورودی

/feed/entry/summary

(در موارد خاص لازم است؛ مشخصات Atom را ببینید.)

 /rss/channel/item/atom:summary
محتوای ورودی

/feed/entry/content

(اگر عنصر محتوا وجود ندارد، ورودی باید حداقل یک عنصر <link rel="alternate"> داشته باشد.)

 /rss/channel/item/description
نویسنده ورودی

/feed/entry/author/name
/feed/entry/author/email

(در موارد خاص لازم است؛ مشخصات Atom را ببینید.)

 /rss/channel/item/author
دسته ورودی /feed/entry/category/@term /rss/channel/item/category
طرح رده ورودی /feed/entry/category/@scheme /rss/channel/item/category/@domain
تاریخ انتشار ورودی /feed/entry/published
(RFC 3339)		 /rss/channel/item/pubDate
(RFC 822)
تاریخ به‌روزرسانی ورودی /feed/entry/updated
(RFC 3339)		 /rss/channel/item/atom:updated
(RFC 3339)

پرس و جوها

این بخش نحوه استفاده از سیستم پرس و جو را توضیح می دهد.

اصول طراحی مدل پرس و جو

مدل پرس و جو عمداً بسیار ساده است. اصول اساسی عبارتند از:

  • کوئری‌ها به‌عنوان URI HTTP بیان می‌شوند، نه به‌عنوان سرصفحه HTTP یا بخشی از بار. یکی از مزایای این روش این است که می توانید به یک پرس و جو پیوند دهید.
  • محمول ها به یک آیتم محدود می شوند. بنابراین، هیچ راهی برای ارسال پرس و جوی همبستگی مانند "یافتن تمام ایمیل های افرادی که امروز حداقل 10 ایمیل برای من ارسال کرده اند" وجود ندارد.
  • مجموعه ای از ویژگی هایی که پرس و جوها می توانند بر آنها گزاره کنند بسیار محدود است. اکثر پرس و جوها صرفاً عبارت جستجوی متن کامل هستند.
  • سفارش نتیجه به اجرا بستگی دارد.
  • پروتکل به طور طبیعی قابل توسعه است. اگر می‌خواهید محموله‌های اضافی یا مرتب‌سازی را در سرویس خود آشکار کنید، می‌توانید این کار را به راحتی از طریق معرفی پارامترهای جدید انجام دهید.

درخواست های پرس و جو

یک کلاینت با صدور یک درخواست HTTP GET از سرویس Google Data درخواست می کند. URI پرس و جو شامل URI منبع (به نام FeedURI در Atom) و به دنبال پارامترهای پرس و جو است. اکثر پارامترهای پرس و جو به عنوان پارامترهای URL سنتی ?name=value[&...] نشان داده می شوند. پارامترهای دسته به طور متفاوتی اداره می شوند. زیر را ببینید.

به عنوان مثال، اگر FeedURI http://www.example.com/feeds/jo باشد، ممکن است یک درخواست با URI زیر ارسال کنید:

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

خدمات Google Data از HTTP Conditional GET پشتیبانی می کند. آنها هدر پاسخ آخرین اصلاح را بر اساس مقدار عنصر <atom:updated> در فید یا ورودی برگشتی تنظیم می کنند. مشتری می تواند این مقدار را به عنوان مقدار سرصفحه درخواست If-Modified-Since برگرداند تا در صورت عدم تغییر محتوا از بازیابی مجدد آن جلوگیری کند. اگر محتوا از زمان If-Modified-Since تغییر نکرده باشد، سرویس Google Data یک پاسخ HTTP 304 (تغییر نشده) را برمی‌گرداند.

یک سرویس داده Google باید از جستارهای دسته بندی و جستارهای alt پشتیبانی کند. پشتیبانی از سایر پارامترها اختیاری است. پاس دادن یک پارامتر استاندارد که توسط یک سرویس مشخص قابل درک نیست منجر به پاسخ 403 Forbidden می شود. ارسال یک پارامتر غیر استاندارد پشتیبانی نشده منجر به پاسخ 400 Bad Request می شود. برای اطلاعات در مورد سایر کدهای وضعیت، به بخش کدهای وضعیت HTTP این سند مراجعه کنید.

پارامترهای پرس و جو استاندارد در جدول زیر خلاصه شده است. همه مقادیر پارامتر باید URL کدگذاری شوند.

پارامتر معنی یادداشت
q رشته پرس و جو تمام متن
  • هنگام ایجاد یک پرس و جو، عبارات جستجو را به صورت q=term1 term2 term3 جدا کنید. (مانند تمام مقادیر پارامتر پرس و جو، فضاها باید با URL کدگذاری شوند.) سرویس Google Data همه ورودی هایی را که با همه عبارت های جستجو مطابقت دارند (مانند استفاده از AND بین عبارت ها) برمی گرداند. مانند جستجوی وب گوگل، سرویس داده های گوگل کلمات کامل (و کلمات مرتبط با همان ریشه) را جستجو می کند، نه رشته های فرعی.
  • برای جستجوی یک عبارت دقیق، عبارت را در گیومه قرار دهید: q="exact phrase".
  • برای حذف ورودی‌هایی که با یک عبارت مشخص مطابقت دارند، از فرم q=-term استفاده کنید.
  • جستجو به حروف بزرگ و کوچک حساس است.
  • مثال: برای جستجوی همه ورودی‌هایی که حاوی عبارت دقیق "الیزابت بنت" و کلمه "دارسی" هستند اما حاوی کلمه "آستن" نیستند، از عبارت زیر استفاده کنید: ?q="Elizabeth Bennet" Darcy -Austen
/-/ category فیلتر دسته
  • هر دسته را طوری فهرست کنید که گویی بخشی از URI منبع است، به شکل /categoryname/ — این یک استثنا برای فرم معمول name=value است.
  • قبل از هر پارامتر پرس و جو، همه دسته ها را فهرست کنید.
  • قبل از دسته اول با /-/ قرار دهید تا مشخص شود که یک دسته است. برای مثال، اگر فید جو دارای دسته‌ای برای ورودی‌های مربوط به فریتز باشد، می‌توانید آن ورودی‌ها را مانند این درخواست کنید: http://www.example.com/feeds/jo/-/Fritz . این به پیاده سازی اجازه می دهد تا URI های پرس و جو مبتنی بر دسته بندی را از URI های منبع متمایز کند.
  • می‌توانید با فهرست کردن پارامترهای دسته‌بندی متعدد، که با اسلش‌ها از هم جدا شده‌اند، در چندین دسته پرس و جو کنید. سرویس Google Data همه ورودی‌هایی را برمی‌گرداند که با همه دسته‌ها مطابقت دارند (مانند استفاده از AND بین عبارت‌ها). به عنوان مثال: http://www.example.com/feeds/jo/-/Fritz/Laurie ورودی هایی را برمی گرداند که با هر دو دسته مطابقت دارند.
  • برای انجام یک OR بین عبارت ها، از یک کاراکتر لوله ( | ) استفاده کنید که با URL کدگذاری شده به عنوان %7C . برای مثال: http://www.example.com/feeds/jo/-/Fritz%7CLaurie ورودی‌هایی را برمی‌گرداند که با هر یک از دسته‌ها مطابقت دارند.
  • یک ورودی با یک دسته مشخص مطابقت دارد اگر ورودی در دسته ای باشد که دارای یک عبارت یا برچسب مطابق تعریف شده در مشخصات Atom باشد. (تقریباً «اصطلاح» رشته داخلی است که توسط نرم‌افزار برای شناسایی دسته استفاده می‌شود، در حالی که «برچسب» رشته‌ای قابل خواندن برای انسان است که در رابط کاربری به کاربر ارائه می‌شود.)
  • برای حذف ورودی‌هایی که با یک دسته خاص مطابقت دارند، از فرم /-categoryname/ استفاده کنید.
  • برای پرس و جو برای دسته ای که طرحی دارد—مانند <category scheme="urn:google.com" term="public"/> — باید طرح را در پرانتزهای مجعد قبل از نام دسته قرار دهید. به عنوان مثال: /{urn:google.com}public . اگر طرح حاوی یک کاراکتر اسلش ( / ) باشد، باید به صورت %2F با URL رمزگذاری شود. برای مطابقت با دسته ای که هیچ طرحی ندارند، از یک جفت بریس مجعد خالی استفاده کنید. اگر بریس‌های فرفری را مشخص نکنید، دسته‌ها در هر طرحی مطابقت دارند.
  • ویژگی های فوق را می توان ترکیب کرد. برای مثال: /A%7C-{urn:google.com}B/-C به معنای (A OR (NOT B)) AND (NOT C) است.
category فیلتر دسته
  • یک راه جایگزین برای انجام فیلتر دسته. این دو روش معادل هستند.
  • برای انجام یک OR بین عبارت‌ها، از یک کاراکتر لوله (|) که با URL کدگذاری شده به عنوان %7C استفاده کنید. به عنوان مثال: http://www.example.com/feeds?category=Fritz%7CLaurie ورودی‌هایی را برمی‌گرداند که با هر دسته مطابقت دارند.
  • برای انجام یک AND بین عبارت ها، از کاراکتر کاما (،) استفاده کنید. برای مثال: http://www.example.com/feeds?category=Fritz,Laurie ورودی هایی را برمی گرداند که با هر دو دسته مطابقت دارند.
author نویسنده ورودی
  • این سرویس ورودی هایی را برمی گرداند که در آن نام نویسنده و/یا آدرس ایمیل با رشته درخواست شما مطابقت دارد.
alt نوع نمایندگی جایگزین
  • اگر پارامتر alt را مشخص نکنید، سرویس یک فید Atom برمی گرداند. این معادل alt=atom است.
  • alt=rss فید نتیجه RSS 2.0 را برمی گرداند.
  • alt=json یک نمایش JSON از فید را برمی‌گرداند. اطلاعات بیشتر
  • alt=json-in-script پاسخی را درخواست می کند که JSON را در یک تگ اسکریپت قرار می دهد. اطلاعات بیشتر
updated-min , updated-max محدودیت ها در تاریخ به روز رسانی ورودی
  • از قالب RFC 3339 timestamp استفاده کنید. به عنوان مثال: 2005-08-09T10:57:00-08:00 .
  • کران پایین شامل است، در حالی که کران بالا منحصر به فرد است.
published-min ، published-max محدوده در تاریخ انتشار ورودی
  • از قالب RFC 3339 timestamp استفاده کنید. به عنوان مثال: 2005-08-09T10:57:00-08:00 .
  • کران پایین شامل است، در حالی که کران بالا منحصر به فرد است.
start-index شاخص 1-مبتنی بر اولین نتیجه ای که باید بازیابی شود
  • توجه داشته باشید که این یک مکانیسم عمومی مکان نما نیست. اگر ابتدا درخواستی را با ?start-index=1&max-results=10 ارسال کنید و سپس پرس و جو دیگری را با ?start-index=11&max-results=10 ارسال کنید، سرویس نمی تواند تضمین کند که نتایج معادل ?start-index=1&max-results=20 هستند. ?start-index=1&max-results=20 ، زیرا درج و حذف ممکن است بین دو پرس و جو صورت گرفته باشد.
max-results حداکثر تعداد نتایجی که باید بازیابی شوند برای هر سرویسی که دارای مقدار max-results پیش‌فرض است (برای محدود کردن اندازه فید پیش‌فرض)، اگر می‌خواهید کل فید را دریافت کنید، می‌توانید تعداد بسیار زیادی را مشخص کنید.
شناسه ورود شناسه یک ورودی خاص که باید بازیابی شود
  • اگر شناسه ورودی را مشخص کنید، نمی توانید هیچ پارامتر دیگری را مشخص کنید.
  • فرم شناسه ورودی توسط سرویس Google Data تعیین می شود.
  • برخلاف بسیاری از پارامترهای پرس و جو، شناسه ورودی به عنوان بخشی از URI مشخص می شود، نه به عنوان یک جفت name=value.
  • مثال: http://www.example.com/feeds/jo/entry1 .

درباره پرس و جوهای دسته بندی

ما تصمیم گرفتیم یک قالب کمی غیرعادی برای جستارهای دسته بندی مشخص کنیم. به جای پرس و جو مانند زیر:

http://example.com/jo?category=Fritz&category=2006

ما استفاده می کنیم:

http://example.com/jo/-/Fritz/2006

این رویکرد یک منبع را بدون استفاده از پارامترهای پرس و جو شناسایی می کند و URI های تمیزتری تولید می کند. ما این رویکرد را برای دسته‌ها انتخاب کردیم زیرا فکر می‌کنیم که پرس‌وجوهای دسته‌بندی رایج‌ترین پرسش‌ها خواهند بود.

اشکال این رویکرد این است که ما از شما می‌خواهیم /-/ در جستارهای دسته‌بندی استفاده کنید، به طوری که سرویس‌های داده Google می‌توانند جستارهای دسته‌بندی را از سایر URI منابع، مانند http://example.com/jo/MyPost/comments متمایز کنند.

پاسخ های پرس و جو

بسته به پارامترهای درخواست، کوئری ها یک فید Atom، یک ورودی Atom یا یک فید RSS را برمی گرداند.

نتایج پرس و جو حاوی عناصر OpenSearch زیر هستند که مستقیماً در زیر عنصر <feed> یا عنصر <channel> قرار دارند (بسته به اینکه آیا نتایج Atom یا RSS هستند):

openSearch:totalResults
تعداد کل نتایج جستجو برای پرس و جو (الزاما همه در فید نتایج موجود نیستند).
openSearch:startIndex
شاخص 1 بر اساس اولین نتیجه.
openSearch:itemsPerPage
حداکثر تعداد مواردی که در یک صفحه ظاهر می شوند. این به مشتریان اجازه می دهد تا پیوندهای مستقیم به هر مجموعه ای از صفحات بعدی ایجاد کنند. با این حال، برای خطر احتمالی در استفاده از این شماره، به یادداشت مربوط به start-index در جدول در بخش درخواست‌های پرس و جو مراجعه کنید.

فید پاسخ Atom و ورودی‌ها ممکن است شامل هر یک از عناصر Atom و Google Data زیر باشد (و همچنین سایر موارد ذکر شده در مشخصات Atom):

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
URI را مشخص می کند که در آن می توان فید کامل Atom را بازیابی کرد.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
PostURI فید Atom (جایی که می توان ورودی های جدید پست کرد) را مشخص می کند.
<link rel="self" type="..." href="..."/>
شامل URI این منبع است. مقدار ویژگی type به فرمت درخواستی بستگی دارد. اگر هیچ داده ای در این میان تغییر نکند، ارسال یک GET دیگر به این URI همان پاسخ را برمی گرداند.
<link rel="previous" type="application/atom+xml" href="..."/>
URI قسمت قبلی مجموعه نتایج پرس و جو را در صورتی که تکه شده باشد مشخص می کند.
<link rel="next" type="application/atom+xml" href="..."/>
URI قسمت بعدی مجموعه نتایج پرس و جو را در صورتی که تکه شده باشد مشخص می کند.
<link rel="edit" type="application/atom+xml" href="..."/>
EditURI ورودی Atom را مشخص می کند (جایی که یک ورودی به روز شده را ارسال می کنید).

در اینجا یک نمونه بدنه پاسخ، در پاسخ به یک عبارت جستجو آمده است:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
  <id>http://www.example.com/feed/1234.1/posts/full</id> 
  <updated>2005-09-16T00:42:06Z</updated> 
  <title type="text">Books and Romance with Jo and Liz</title> 
  <link rel="alternate" type="text/html" href="http://www.example.net/"/> 
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="self" type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <generator version="1.0"
    uri="http://www.example.com">Example Generator Engine</generator> 
  <openSearch:totalResults>2</openSearch:totalResults> 
  <openSearch:startIndex>0</openSearch:startIndex> 
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> 
    <published>2005-01-09T08:00:00Z</published> 
    <updated>2005-01-09T08:00:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1009</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> 
    <published>2005-01-07T08:00:00Z</published> 
    <updated>2005-01-07T08:02:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1007</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
</feed>

اگر فید درخواستی در قالب Atom باشد، اگر هیچ پارامتر پرس و جو مشخص نشده باشد، و اگر نتیجه شامل تمام ورودی ها نباشد، عنصر زیر در فید سطح بالا درج می شود: <link rel="next" type="application/atom+xml" href="..."/> . به فید حاوی مجموعه ورودی های بعدی اشاره می کند. مجموعه‌های بعدی حاوی عنصر <link rel="previous" type="application/atom+xml" href="..."/> مربوطه هستند. با دنبال کردن تمام پیوندهای بعدی ، یک مشتری می تواند تمام ورودی ها را از یک فید بازیابی کند.

کدهای وضعیت HTTP

جدول زیر معنی کدهای وضعیت HTTP مختلف را در زمینه خدمات Google Data توضیح می دهد.

کد توضیح
200 باشه بدون خطا.
201 ایجاد شد ایجاد یک منبع موفقیت آمیز بود.
304 تغییر نکرده است منبع از زمان مشخص شده در هدر If-Modified-Since درخواست تغییر نکرده است.
400 درخواست بد URI یا هدر درخواست نامعتبر یا پارامتر غیر استاندارد پشتیبانی نشده.
401 غیر مجاز مجوز لازم است.
403 ممنوع پارامتر استاندارد پشتیبانی نشده، یا احراز هویت یا مجوز انجام نشد.
404 پیدا نشد منبع (مانند فید یا ورودی) یافت نشد.
409 درگیری شماره نسخه مشخص شده با آخرین شماره نسخه منبع مطابقت ندارد.
500 خطای سرور داخلی خطای داخلی. این کد پیش فرضی است که برای تمام خطاهای شناسایی نشده استفاده می شود.

همزمانی خوش بینانه (نسخه سازی)

گاهی اوقات مهم است که اطمینان حاصل شود که چندین مشتری سهواً تغییرات یکدیگر را بازنویسی نمی کنند. این به راحتی با اطمینان از اینکه نسخه فعلی ورودی که یک کلاینت در حال تغییر آن است، با نسخه ای که مشتری بر اساس آن تغییرات را انجام می دهد، انجام می شود. اگر کلاینت دوم قبل از اولین کلاینت به‌روزرسانی انجام دهد، به‌روزرسانی مشتری اول رد می‌شود، زیرا مشتری اول دیگر تغییرات خود را بر اساس آخرین نسخه انجام نمی‌دهد.

در فیدهای Google Data که از نسخه‌سازی پشتیبانی می‌کنند، با افزودن شناسه نسخه به EditURI هر ورودی، به این معناها دست پیدا می‌کنیم. توجه داشته باشید که فقط EditURI تحت تأثیر قرار می گیرد، نه شناسه ورودی. در این طرح، هر به روز رسانی EditURI ورودی را تغییر می دهد، بنابراین تضمین می کند که به روز رسانی های بعدی بر اساس نسخه اصلی شکست می خورند. البته حذف‌ها با توجه به این ویژگی مشابه به‌روزرسانی‌ها هستند. اگر حذفی را با شماره نسخه قدیمی ارسال کنید، حذف انجام نمی شود.

همه فیدهای Google Data از همزمانی خوش بینانه پشتیبانی نمی کنند. در یک فید که از آن پشتیبانی می کند، اگر سرور تضاد نسخه را در PUT یا DELETE تشخیص دهد، سرور با 409 Conflict پاسخ می دهد. بدنه پاسخ شامل وضعیت فعلی ورودی (یک سند ورودی اتم) است. به مشتری توصیه می شود با استفاده از EditURI از پاسخ 409، تضاد را حل کند و درخواست را دوباره ارسال کند.

یادداشت های انگیزشی و طراحی

این رویکرد به همزمانی خوش‌بینانه به ما امکان می‌دهد بدون نیاز به نشانه‌گذاری جدید برای شناسه‌های نسخه، معنایی را که می‌خواهیم پیاده‌سازی کنیم، که پاسخ‌های Google Data را با نقاط پایانی غیر Google Data Atom سازگار می‌کند.

به جای تعیین شناسه‌های نسخه، می‌توانستیم به مهر زمانی به‌روزرسانی در هر ورودی نگاه کنیم ( /atom:entry/atom:updated ). با این حال، دو مشکل در استفاده از مهر زمانی به‌روزرسانی وجود دارد:

  • این فقط برای به روز رسانی و نه حذف کار می کند.
  • این برنامه‌ها را مجبور می‌کند از مقادیر تاریخ/زمان به‌عنوان شناسه‌های نسخه استفاده کنند، که این امر به‌روزرسانی Google Data را در بالای بسیاری از فروشگاه‌های داده موجود دشوارتر می‌کند.

احراز هویت

هنگامی که یک سرویس گیرنده سعی می کند به یک سرویس دسترسی پیدا کند، ممکن است نیاز داشته باشد که اعتبار کاربر را به سرویس ارائه دهد تا نشان دهد که کاربر صلاحیت انجام عمل مورد نظر را دارد.

رویکردی که یک کلاینت باید برای احراز هویت استفاده کند به نوع مشتری بستگی دارد:

  • یک برنامه دسکتاپ باید از یک سیستم احراز هویت خاص گوگل به نام احراز هویت حساب برای برنامه های نصب شده (همچنین به عنوان "ClientLogin" شناخته می شود) استفاده کند. (کلاینت های مبتنی بر وب نباید از این سیستم استفاده کنند.)
  • یک کلاینت مبتنی بر وب، مانند یک فرانت اند شخص ثالث برای سرویس Google Data، باید از یک سیستم احراز هویت خاص Google به نام Account Authentication Proxy برای برنامه های مبتنی بر وب (همچنین به عنوان "AuthSub" شناخته می شود) استفاده کند.

در سیستم ClientLogin، سرویس گیرنده دسکتاپ از کاربر اعتبارنامه خود را می خواهد و سپس آن اعتبار را به سیستم احراز هویت گوگل ارسال می کند.

اگر احراز هویت با موفقیت انجام شود، سیستم احراز هویت رمزی را برمی‌گرداند که مشتری متعاقباً هنگام ارسال درخواست‌های Google Data از آن (در سرصفحه مجوز HTTP) استفاده می‌کند.

اگر احراز هویت ناموفق باشد، سرور یک کد وضعیت 403 Forbidden را به همراه یک هدر WWW-Authenticate که حاوی چالش قابل اجرا برای احراز هویت است، برمی‌گرداند.

سیستم AuthSub نیز به همین صورت عمل می کند، با این تفاوت که به جای اینکه از کاربر اطلاعات کاربری خود را بپرسد، کاربر را به سرویس گوگل متصل می کند که درخواست اعتبار می کند. سپس این سرویس رمزی را برمی گرداند که برنامه وب می تواند از آن استفاده کند. مزیت این رویکرد این است که گوگل (به جای وب سایت) به طور ایمن اعتبار کاربر را مدیریت و ذخیره می کند.

برای جزئیات بیشتر درباره این سیستم‌های احراز هویت، به نمای کلی تأیید هویت داده‌های Google یا مستندات تأیید اعتبار حساب Google مراجعه کنید.

وضعیت جلسه

بسیاری از پیاده‌سازی‌های منطق کسب‌وکار نیاز به چسبندگی جلسه دارند - ردیابی وضعیت جلسه کاربر.

گوگل وضعیت جلسه را به دو صورت ردیابی می کند: استفاده از کوکی ها و استفاده از رمزی که می تواند به عنوان پارامتر پرس و جو ارسال شود. هر دو روش به یک اثر می رسند. توصیه می‌کنیم مشتریان از یکی از این روش‌های ردیابی وضعیت جلسه پشتیبانی کنند (هر کدام کافی است). اگر مشتری از هیچ یک از این روش‌ها پشتیبانی نکند، آن مشتری همچنان با سرویس‌های Google Data کار می‌کند، اما عملکرد ممکن است در مقایسه با کلاینت‌هایی که از این روش‌ها پشتیبانی می‌کنند، آسیب ببیند. به طور خاص، اگر یک کلاینت از این روش‌ها پشتیبانی نکند، هر درخواست منجر به تغییر مسیر می‌شود و بنابراین هر درخواست (و هر داده مرتبط) دو بار به سرور ارسال می‌شود که بر عملکرد مشتری و سرور تأثیر می‌گذارد.

کتابخانه‌های سرویس گیرنده Google وضعیت جلسه را برای شما مدیریت می‌کنند، بنابراین اگر از کتابخانه‌های ما استفاده می‌کنید، برای دریافت پشتیبانی وضعیت جلسه نیازی به انجام کاری ندارید.

منابع اضافی

ممکن است اسناد شخص ثالث زیر برای شما مفید باشد:

بازگشت به بالا