مرجع پروتکل

اخطار : این صفحه درباره APIهای قدیمی Google، Google Data APIها است. فقط مربوط به APIهایی است که در فهرست راهنمای Google Data APIs فهرست شده اند، که بسیاری از آنها با APIهای جدیدتر جایگزین شده اند. برای اطلاعات در مورد یک API جدید خاص، به مستندات API جدید مراجعه کنید. برای اطلاعات در مورد تأیید درخواست‌ها با یک API جدیدتر، به تأیید اعتبار و مجوز حساب‌های Google مراجعه کنید.

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

برای کسب اطلاعات بیشتر در مورد پروتکل داده های Google، به صفحه نمای کلی راهنمای توسعه دهنده و سند اصول پروتکل مراجعه کنید.

حضار

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

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

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

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

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

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

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

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

فرمت سند

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

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

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

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

نکته: این خلاصه از نماد استاندارد XPath استفاده می کند: به ویژه، اسلش ها سلسله مراتب عنصر را نشان می دهند و علامت @ نشان دهنده ویژگی یک عنصر است.

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

جدول زیر عناصر فید پروتکل داده گوگل را نشان می دهد:

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

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

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

تاریخ آخرین به روز رسانی خوراک /feed/updated
(فرمت RFC 3339)
دسته خوراک /feed/category/@term
طرح طبقه بندی خوراک /feed/category/@scheme
مولد خوراک /feed/generator
/feed/generator/@uri
نماد فید /feed/icon
آرم فید /feed/logo

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

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

جدول زیر عناصر ورودی پروتکل داده گوگل را نشان می دهد:

آیتم طرحواره ورودی نمایندگی اتم
شناسه ورودی /feed/entry/id
عنوان ورودی /feed/entry/title
لینک ورود /feed/entry/link
خلاصه ورودی

/feed/entry/summary

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

محتوای ورودی

/feed/entry/content

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

نویسنده ورودی

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

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

دسته ورودی /feed/entry/category/@term
طرح رده ورودی /feed/entry/category/@scheme
تاریخ انتشار ورودی /feed/entry/published
(RFC 3339)
تاریخ به‌روزرسانی ورودی /feed/entry/updated
(RFC 3339)

پرس و جوها

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

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

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

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

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

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

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

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

پارامتر معنی یادداشت
alt نوع نمایندگی جایگزین
  • اگر پارامتر alt را مشخص نکنید، سرویس یک فید Atom برمی گرداند. این معادل alt=atom است.
  • alt=rss فید نتیجه RSS 2.0 را برمی گرداند (فقط برای خواندن). هنگامی که از یک سرویس با فرمت RSS داده درخواست می کنید، سرویس یک فید (یا دیگر نمایش منبع) را در قالب RSS ارائه می دهد. اگر ویژگی RSS معادلی برای یک ویژگی Data API داده شده وجود نداشته باشد، این سرویس از ویژگی Atom استفاده می کند و آن را با یک فضای نام مناسب برچسب گذاری می کند تا نشان دهد که پسوند RSS است.
  • alt=json یک نمایش JSON از فید را برمی‌گرداند. اطلاعات بیشتر
  • alt=json-in-script پاسخی را درخواست می کند که JSON را در یک تگ اسکریپت قرار می دهد. اطلاعات بیشتر
  • alt=atom-in-script یک پاسخ Atom را درخواست می کند که یک رشته XML را در یک تگ اسکریپت می پیچد.
  • alt=rss-in-script یک پاسخ RSS را درخواست می کند که یک رشته XML را در یک تگ اسکریپت می پیچد.
  • alt=atom-service یک سند سرویس Atom را درخواست می کند که فید را توصیف کند.
author نویسنده ورودی
  • این سرویس ورودی هایی را برمی گرداند که در آن نام نویسنده و/یا آدرس ایمیل با رشته درخواست شما مطابقت دارد.
category فیلتر پرس و جو دسته
  • یک راه جایگزین برای انجام فیلتر دسته. این دو روش معادل هستند.
  • برای انجام یک OR بین عبارت‌ها، از یک کاراکتر لوله (|) که با URL کدگذاری شده به عنوان %7C استفاده کنید. به عنوان مثال: http://www.example.com/feeds?category=Fritz%7CLaurie ورودی‌هایی را برمی‌گرداند که با هر دسته مطابقت دارند.
  • برای انجام یک AND بین عبارت ها، از کاراکتر کاما (،) استفاده کنید. برای مثال: http://www.example.com/feeds?category=Fritz,Laurie ورودی هایی را برمی گرداند که با هر دو دسته مطابقت دارند.
/-/ category فیلتر پرس و جو دسته
  • هر دسته را طوری فهرست کنید که گویی بخشی از URI منبع است، به شکل /categoryname/ — این یک استثنا برای فرم معمول name=value است.
  • قبل از هر پارامتر پرس و جو، همه دسته ها را فهرست کنید.
  • قبل از دسته اول با /-/ قرار دهید تا مشخص شود که یک دسته است. برای مثال، اگر فید جو دارای دسته‌ای برای ورودی‌های مربوط به فریتز باشد، می‌توانید آن ورودی‌ها را مانند این درخواست کنید: http://www.example.com/feeds/jo/-/Fritz . این به پیاده سازی اجازه می دهد تا URI های پرس و جو مبتنی بر دسته بندی را از URI های منبع متمایز کند.
  • می‌توانید با فهرست کردن پارامترهای دسته‌بندی متعدد، که با اسلش‌ها از هم جدا شده‌اند، در چندین دسته پرس و جو کنید. این سرویس همه ورودی‌هایی را که با همه دسته‌ها مطابقت دارند، برمی‌گرداند (مانند استفاده از 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) است.
شناسه ورود شناسه یک ورودی خاص که باید بازیابی شود
  • اگر شناسه ورودی را مشخص کنید، نمی توانید هیچ پارامتر دیگری را مشخص کنید.
  • فرم شناسه ورودی توسط سرویس تعیین می شود.
  • برخلاف بسیاری از پارامترهای پرس و جو، شناسه ورودی به عنوان بخشی از URI مشخص می شود، نه به عنوان یک جفت name=value.
  • مثال: http://www.example.com/feeds/jo/entry1 .
fields فیلتر پاسخ
  • به جای نمایش کامل منبع، فقط فیلدهای درخواستی را برمی گرداند. مثلا:
    http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))
    هنگامی که این درخواست را دریافت می کند، سرور پاسخی را برمی گرداند که فقط حاوی پیوند و عناصر ورودی برای فید است. علاوه بر این، عناصر ورودی بازگردانده شده، ورودی های جزئی هستند که فقط حاوی ETag، ID، به روز شده و روابط پیوند ویرایش هستند.
  • مقدار فیلدها باید مانند تمام مقادیر پارامترهای پرس و جو دارای کد URL باشند.
  • برای اطلاعات بیشتر، بخش پاسخ بخشی را ببینید.
  • این پارامتر در حال حاضر یک ویژگی آزمایشی است.
max-results حداکثر تعداد نتایجی که باید بازیابی شوند برای هر سرویسی که دارای مقدار max-results پیش‌فرض است (برای محدود کردن اندازه فید پیش‌فرض)، اگر می‌خواهید کل فید را دریافت کنید، می‌توانید تعداد بسیار زیادی را مشخص کنید.
prettyprint یک پاسخ XML را با شناسه‌ها و شکستگی‌های خط برمی‌گرداند
  • اگر prettyprint=true ، XML بازگردانده شده توسط سرور قابل خواندن توسط انسان خواهد بود (خیلی چاپ شده).
  • پیش فرض: prettyprint=false
published-min ، published-max محدوده در تاریخ انتشار ورودی
  • از قالب RFC 3339 timestamp استفاده کنید. به عنوان مثال: 2005-08-09T10:57:00-08:00 .
  • کران پایین شامل است، در حالی که کران بالا منحصر به فرد است.
q رشته پرس و جو تمام متن
  • هنگام ایجاد یک پرس و جو، عبارات جستجو را به صورت q=term1 term2 term3 جدا کنید. (مانند تمام مقادیر پارامتر پرس و جو، فضاها باید با URL رمزگذاری شوند.) این سرویس همه ورودی هایی را که با تمام عبارات جستجو مطابقت دارند (مانند استفاده از AND بین عبارت ها) برمی گرداند. مانند جستجوی وب گوگل، یک سرویس بر روی کلمات کامل (و کلمات مرتبط با همان ریشه) جستجو می کند، نه رشته های فرعی.
  • برای جستجوی یک عبارت دقیق، عبارت را در گیومه قرار دهید: q="exact phrase".
  • برای حذف ورودی‌هایی که با یک عبارت مشخص مطابقت دارند، از فرم q=-term استفاده کنید.
  • جستجو به حروف بزرگ و کوچک حساس است.
  • مثال: برای جستجوی همه ورودی‌هایی که حاوی عبارت دقیق "الیزابت بنت" و کلمه "دارسی" هستند اما حاوی کلمه "آستن" نیستند، از عبارت زیر استفاده کنید: ?q="Elizabeth Bennet" Darcy -Austen
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 ، زیرا درج و حذف ممکن است بین دو پرس و جو صورت گرفته باشد.
strict بررسی دقیق پارامتر پرس و جو
  • برای تأیید اینکه هر یک از پارامترهای کوئری شما توسط سرویس شناسایی می شوند، strict=true را تنظیم کنید. اگر پارامتری شناسایی نشود، خطا برمی گردد.
  • پیش فرض: strict=false
updated-min , updated-max محدودیت ها در تاریخ به روز رسانی ورودی
  • از قالب RFC 3339 timestamp استفاده کنید. به عنوان مثال: 2005-08-09T10:57:00-08:00 .
  • کران پایین شامل است، در حالی که کران بالا منحصر به فرد است.
  • در برخی موارد (مانند هنگام استفاده از نسخه 2.1 یا جدیدتر از API Calendar Data)، تعیین یک updated-min که در گذشته بسیار دور است، باعث می شود وضعیت HTTP 410 (Gone) برگردد.

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

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

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

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

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

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

اشکال این رویکرد این است که ما از شما می‌خواهیم از /-/ در این نوع جستارهای دسته‌بندی استفاده کنید، به طوری که سرویس‌ها می‌توانند جستارهای دسته‌بندی را از سایر 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 و Data API زیر باشد (و همچنین سایر موارد ذکر شده در مشخصات 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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 مختلف در زمینه APIهای داده را توضیح می دهد.

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

نسخه‌سازی منابع (ETags)

گاهی اوقات باید بتوانید به نسخه خاصی از یک ورودی خاص مراجعه کنید.

این امر به ویژه در دو مورد مهم است:

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

APIهای Google Data هر دوی این موارد را با استفاده از ETags ، بخشی استاندارد از HTTP، مدیریت می‌کنند.

ETag یک شناسه است که یک نسخه خاص از یک ورودی خاص را مشخص می کند. سرور یک ETag را به عناصر ورودی و فید متصل می کند که برای مشتریان ارسال می کند. هنگامی که یک ورودی یا فید تغییر می کند، ETag آن نیز تغییر می کند.

APIهای Google Data تگ‌های ET را در دو مکان ارائه می‌کنند: در یک هدر HTTP ETag و در یک ویژگی gd:etag از عناصر <feed> و <entry> .

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

دو نوع ETag وجود دارد: قوی و ضعیف. ETag های قوی یک نسخه خاص از یک ورودی خاص را شناسایی می کنند و می توانند برای جلوگیری از بازنویسی تغییرات سایر مشتریان استفاده شوند. تگ های ضعیف، در زمینه Google Data API، فقط برای بازیابی مشروط استفاده می شوند. یک ETag ضعیف همیشه با W/ شروع می شود. به عنوان مثال: W/"D08FQn8-eil7ImA9WxZbFEw."

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

در اینجا نمونه‌ای از فید (شامل برخی از هدرهای HTTP) بازیابی شده از سرویسی است که از تگ‌های ET قوی پشتیبانی می‌کند:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

کتابخانه های سرویس گیرنده ای که از نسخه 2 API های داده پشتیبانی می کنند، ETag ها را برای شما به طور شفاف مدیریت می کنند. اطلاعات زیر برای مشتریانی است که از کتابخانه های سرویس گیرنده استفاده نمی کنند، و برای خوانندگانی که علاقه مند به نحوه مدیریت نسخه در سطح پروتکل هستند.

توجه : برای اطلاعات در مورد سیستم نسخه‌سازی منابع مورد استفاده در نسخه 1.0 APIهای داده، به راهنمای مرجع 1.0 مراجعه کنید.

بازیابی مشروط

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

برای انجام این نوع بازیابی مشروط، یک درخواست HTTP GET ارسال کنید که شامل سرصفحه HTTP If-None-Match است. در هدر، ETag ورودی را مشخص کنید.

در اینجا نمونه ای از هدر If-None-Match آورده شده است:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

هنگامی که سرور این درخواست را دریافت می کند، بررسی می کند که آیا ورودیی که درخواست کرده اید دارای ETag مشابه با ETagی است که شما تعیین کرده اید. اگر تگ‌های ET مطابقت داشته باشند، ورودی تغییر نکرده است و سرور کد وضعیت HTTP 304 Not Modified را برمی‌گرداند.

اگر تگ های ET با هم مطابقت نداشته باشند، پس از آخرین باری که شما آن را درخواست کرده اید، ورودی اصلاح شده است و سرور ورودی را برمی گرداند.

به روز رسانی ورودی ها

ساده ترین راه برای جلوگیری از رونویسی تغییرات مشتری دیگر این است که سرور مطمئن شود که وقتی مشتری شما یک ورودی به روز شده ارسال می کند، نسخه ورودی که مشتری شما با آن شروع کرده است با نسخه فعلی ذخیره شده توسط سرور یکسان است. اگر مشتری دوم قبل از اینکه کلاینت شما بروزرسانی کند، به روز رسانی مشتری شما رد می شود، زیرا مشتری شما دیگر تغییرات خود را بر اساس آخرین نسخه انجام نمی دهد.

هنگامی که مشتری شما داده‌ها را از سرویسی بازیابی می‌کند که از ETag‌های قوی پشتیبانی می‌کند، هر ورودی دارای یک ETag است که به عنوان یک شناسه نسخه منحصر به فرد برای آن نسخه از آن ورودی عمل می‌کند.

توجه : به روز رسانی با استفاده از تگ های ET فقط با ETag های قوی کار می کند. برای سرویس‌هایی که تگ‌های ضعیف ET ارائه می‌کنند، همه به‌روزرسانی‌ها با موفقیت انجام می‌شوند، صرف نظر از اینکه شخص دیگری از زمانی که شما آن را بازیابی کرده‌اید، آن را به‌روزرسانی کرده است یا خیر. جدیدترین به‌روزرسانی همیشه سایر به‌روزرسانی‌های قبلی را بازنویسی می‌کند. بنابراین هنگام به روز رسانی یا حذف تگ های ضعیف ارسال نکنید. اگر این کار را انجام دهید یک پیغام خطا دریافت خواهید کرد.

بنابراین هنگامی که مشتری شما یک به روز رسانی را به یک سرویس قوی ETags ارسال می کند، باید مشخص کند که چه نسخه ای از ورودی را به روز می کند. دو راه برای انجام آن وجود دارد:

  • از هدر If-Match HTTP استفاده کنید.
  • از ویژگی gd:etag در عنصر <atom:entry> استفاده کنید.

ما در صورت امکان رویکرد If-Match را توصیه می کنیم.

برای به‌روزرسانی یک ورودی با استفاده از If-Match ، با دریافت ورودی که در حال به‌روزرسانی هستید، شروع کنید. هر تغییر دلخواه را در ورودی انجام دهید، سپس یک درخواست PUT جدید حاوی ورودی اصلاح شده ایجاد کنید. (برای جزئیات آدرس‌های اینترنتی مورد استفاده، به مستندات خدمات خاص مراجعه کنید.)

قبل از ارسال PUT ، یک هدر HTTP If-Match حاوی ETag از ورودی اصلی اضافه کنید:

If-Match: "S0wCTlpIIip7ImA0X0QI"

سپس درخواست PUT ارسال کنید.

اگر به روز رسانی با موفقیت انجام شود، سرور یک کد وضعیت HTTP 200 OK و یک کپی از ورودی به روز شده را برمی گرداند.

اگر به‌روزرسانی ناموفق باشد زیرا ETag که مشخص کرده‌اید با ETag فعلی ورودی مطابقت ندارد (که به این معنی است که ورودی از آخرین باری که آن را بازیابی کرده‌اید در سرور تغییر کرده است)، سرور یک کد وضعیت HTTP 412 Precondition Failed را برمی‌گرداند.

اگر نمی توانید به راحتی سرصفحه های HTTP بنویسید، یا دلیل دیگری برای اجتناب از استفاده از هدر If-Match دارید، می توانید به جای آن از ویژگی gd:etag استفاده کنید.

اگر سرصفحه If-Match ارسال نکنید، سرور از مقدار ویژگی gd:etag ورودی به روز شده به عنوان مقدار If-Match ضمنی استفاده می کند.

برای نادیده گرفتن سیستم نسخه‌سازی و به‌روزرسانی ورودی بدون توجه به اینکه آیا شخص دیگری آن را از زمانی که شما آن را بازیابی کرده‌اید به‌روزرسانی کرده است یا خیر، از If-Match: * به جای تعیین ETag در سربرگ استفاده کنید.

برای اطلاعات در مورد اینکه کدام سرویس‌ها از ETag‌های قوی پشتیبانی می‌کنند، به راهنمای مهاجرت مراجعه کنید.

حذف ورودی ها

حذف ورودی هایی که از تگ های ET قوی استفاده می کنند بسیار شبیه به روز رسانی آنها است.

برای حذف یک ورودی که دارای ETag قوی است، ابتدا ورودی مورد نظر برای حذف را بازیابی می کنید، سپس یک درخواست DELETE را به URL ویرایش ورودی ارسال می کنید.

اگر می‌خواهید مطمئن شوید ورودی‌ای را که از زمان بازیابی توسط کلاینت دیگری تغییر کرده است، حذف نمی‌کنید، یک سرصفحه HTTP If-Match که حاوی مقدار ETag ورودی اصلی است، اضافه کنید.

اگر می‌خواهید سیستم نسخه‌سازی را لغو کنید و ورودی را بدون توجه به اینکه شخص دیگری از زمان بازیابی آن به‌روزرسانی کرده است حذف کنید، به جای تعیین ETag در هدر از If-Match: * استفاده کنید.

اگر ورودی دارای ETag قوی نباشد، درخواست DELETE همیشه موفق می شود.

پاسخ جزئی (تجربی)

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

برای اطلاع از وجود پاسخ جزئی برای محصولی که استفاده می‌کنید، به مستندات API آن مراجعه کنید.

برای درخواست پاسخ جزئی، از پارامتر پرس و جو fields برای تعیین عناصر یا ویژگی هایی که می خواهید برگردانده شوند، استفاده کنید. در اینجا یک مثال است:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

پاسخ سرور فقط شامل پیوند و عناصر ورودی برای فید است. عناصر ورودی فقط حاوی ETag، ID، اطلاعات پیوند به روز شده و ویرایش هستند. نحو پارامتر پرس و جو fields در بخش های زیر پوشش داده شده است. برای جزئیات بیشتر درباره پاسخ، به مدیریت پاسخ‌های جزئی مراجعه کنید.

توجه : می توانید از پارامتر پرس و جو fields برای هر درخواستی که داده را برمی گرداند استفاده کنید. علاوه بر GET ، این شامل POST و PUT (و همچنین PATCH است که برای ایجاد به‌روزرسانی‌های جزئی استفاده می‌شود). با این حال، پارامتر پرس و جو fields تنها بر داده های پاسخ تأثیر می گذارد. بر داده هایی که باید ارائه دهید یا اینکه کدام فیلدها به روز می شوند یا ایجاد می شوند تأثیر نمی گذارد.

خلاصه نحو پارامتر فیلدها

فرمت مقدار پارامتر پرس و fields بر اساس نحو XPath است. با این حال، تنها زیر مجموعه ای از عبارات معتبر XPath را پشتیبانی می کند. نحو پشتیبانی شده در زیر خلاصه شده است و نمونه های اضافی در بخش زیر ارائه شده است.

  • از یک لیست جدا شده با کاما برای انتخاب چندین فیلد استفاده کنید.
  • از a/b برای انتخاب عنصر b که درون عنصر a تودرتو است استفاده کنید. از a/b/c برای انتخاب عنصر c تو در تو در b استفاده کنید.
  • از پیشوند '@' برای شناسایی یک ویژگی با نام داده شده استفاده کنید. برای اشاره به یک عنصر، پیشوند '@' را حذف کنید.
  • شرایط فیلد را برای انتخاب عناصری که با معیارهای خاصی مطابقت دارند، با قرار دادن عبارات در پرانتز " [ ] " بعد از عنصری که می خواهید محدود کنید، اعمال کنید.

    برای مثال، fields=entry[author/name='Elizabeth'] فقط ورودی‌هایی را برمی‌گرداند که الیزابت نویسنده آن‌ها است.

  • انتخابگرهای فرعی فیلد را مشخص کنید تا فقط ویژگی ها یا عناصر فرعی خاص را با قرار دادن عبارات در پرانتز " ( ) " پس از هر عنصر انتخاب شده درخواست کنند.

    برای مثال، fields=entry(id,author/email) فقط شناسه و ایمیل نویسنده را برای هر ورودی فید برمی گرداند.

  • شما می توانید رشته ها را با استفاده از گیومه های دوتایی یا تکی مشخص کنید .

    برای فرار از یک نقل قول دوتایی یا تکی، نقل قول را تکرار کنید . به عنوان مثال، """Hello,"" he said" رشته "Hello," he said را تولید می‌کند و '''Hello,'' he said' رشته 'Hello,' he said تولید می‌کند.
  • شما می توانید از حروف عام در انتخاب زمینه استفاده کنید.

    برای مثال، entry/gd:* همه عناصر فرزند ورودی را در فضای نام gd انتخاب می‌کند، و entry/@gd:* ویژگی‌های عنصر فرزند را در همان فضای نام انتخاب می‌کند.

پارامتر پرس و جو fields به عنوان فیلتر خروجی عمل می کند. این بدان معنی است که پاسخ جزئی تنها پس از پردازش بقیه پرس و جو محاسبه می شود. برای مثال، اگر یک پارامتر query max-results را نیز مشخص کنید تا نشان دهد که در هر صفحه 20 نتیجه می‌خواهید، 20 نتیجه اول تولید می‌شوند و پاسخ جزئی از آن محاسبه می‌شود. اگر مشخصات fields با هیچ یک از 20 ورودی اول انتخاب شده توسط پرس و جو مطابقت نداشته باشد، یک فید خالی دریافت می کنید. شما 20 ورودی منطبق را پس نمی گیرید.

توجه: سعی نکنید از شرایط فیلد به عنوان انتخابگر پرس و جو استفاده کنید. یعنی سعی نکنید یک فید کامل را بازیابی کنید و شرایط فیلد را برای فیلتر کردن موارد مورد علاقه از یک مجموعه داده بسیار بزرگ اعمال کنید. در صورت امکان، از پارامترهای دیگر پرس و جو مانند start-index و max-results استفاده کنید تا نتایج هر پرس و جو را به اندازه قابل مدیریت کاهش دهید. در غیر این صورت، افزایش عملکرد ممکن با پاسخ نسبی می تواند با کاهش جدی عملکرد ناشی از استفاده نادرست جبران شود.

فرمت کردن مقدار پارامتر فیلدها

دستورالعمل های زیر نحوه ساخت مقدار پارامتر پرس و جو fields را توضیح می دهد. هر دستورالعمل شامل مثال‌هایی است و توضیحاتی در مورد چگونگی تأثیر مقدار پارامتر بر پاسخ ارائه می‌دهد.

توجه: مانند تمام مقادیر پارامتر پرس و جو، مقدار پارامتر fields باید با URL رمزگذاری شده باشد. برای خوانایی بهتر، مثال‌های زیر کدگذاری را حذف کرده‌اند.

فیلدهایی را که می خواهید برگردانید شناسایی کنید یا فیلدهایی را انتخاب کنید.
مقدار پارامتر پرس و جو fields ، فهرستی از عناصر یا ویژگی‌های جدا شده با کاما است (که در مجموع فیلد نامیده می‌شوند)، و هر فیلد نسبت به عنصر اصلی نمایش منبع مشخص می‌شود. بنابراین، اگر یک فید را بازیابی می کنید، فیلدها نسبت به عنصر <feed> مشخص می شوند و اگر یک ورودی را بازیابی می کنید، فیلدها نسبت به عنصر <entry> مشخص می شوند. اگر عنصری که انتخاب می‌کنید یک عنصر تکرار شونده در فید باشد (یا بخشی از آن باشد)، سرویس تمام نمونه‌های آن عنصر را برمی‌گرداند.

در اینجا چند نمونه در سطح خوراک آورده شده است:
مثال ها اثر
entry همه عناصر <entry> و همه عناصر فرعی آن ورودی‌ها را برمی‌گرداند، اما هیچ عنصر فرزند دیگری از <feed> را برمی‌گرداند.
id,entry هم فید <id> و هم همه عناصر <entry> را برمی گرداند.
entry/title عنصر <title> را برای همه ورودی‌های فید برمی‌گرداند.

هر زمان که یک عنصر تودرتو برگردانده می شود، پاسخ شامل برچسب های محصور برای هر یک است عناصر والد تگ‌های والد شامل هیچ عنصر یا ویژگی فرزند دیگری نمی‌شوند، مگر اینکه به صراحت انتخاب شده باشند.
entry/author/uri فقط عنصر فرعی <uri> عنصر <author> را برای همه ورودی‌های فید برمی‌گرداند.
entry/*:rating فقط عناصر فرعی را با rating نام محلی در هر فضای نامی برای همه ورودی‌های فید برمی‌گرداند.

در اینجا چند نمونه سطح ورودی آورده شده است:
مثال ها اثر
author عنصر فرزند <author> ورودی هدف را برمی گرداند.
@gd:etag ویژگی etag ورودی هدف را برمی‌گرداند.
author/uri عنصر فرعی <uri> عنصر <author> را برای ورودی هدف برمی‌گرداند.
media:group/media:* تمام فیلدهای فرعی <media:group> را در فضای نام media برای ورودی هدف برمی‌گرداند.
پاسخ را به فیلدهای انتخابی که با معیارهای خاصی مطابقت دارند محدود کنید یا از شرایط فیلد استفاده کنید.
به طور پیش فرض، اگر درخواست شما عنصری را مشخص می کند که بیش از یک بار اتفاق می افتد، پاسخ جزئی شامل تمام نمونه های آن عنصر می شود. با این حال، شما همچنین می توانید مشخص کنید که پاسخ باید فقط شامل عناصری باشد که دارای یک مقدار مشخصه خاص هستند یا عناصری که شرایط دیگری را با استفاده از نحو " [ ] " برآورده می کنند، همانطور که در مثال های زیر نشان داده شده است. برای جزئیات بیشتر به بخش نحو شرایط فیلد مراجعه کنید.
مثال ها اثر
entry[link/@rel='edit'] هر ورودی فید حاوی عنصر <link> با مقدار ویژگی rel 'edit' را برمی‌گرداند.
entry/title[text()='Today'] اگر محتوای آنها 'Today' باشد، هر عنصر <title> را که در ورودی‌های فید رخ می‌دهد برمی‌گرداند.
entry/author[name='Jo'] هر عنصر <author> را که در ورودی‌های فید رخ می‌دهد، در صورتی که یک عنصر فرعی <name> با محتوای 'Jo' داشته باشند، برمی‌گرداند.
author[name='Jo'] عنصر <author> را در ورودی هدف برمی‌گرداند اگر عنصر فرعی <name> با محتوای 'Jo' داشته باشد.
فقط بخش‌هایی از عناصر انتخاب‌شده را درخواست کنید یا از زیرمجموعه‌های فیلد استفاده کنید.
به طور پیش فرض، اگر درخواست شما عناصر خاصی را مشخص می کند، سرویس عناصر را به طور کامل برمی گرداند. شما می توانید مشخص کنید که پاسخ فقط شامل عناصر فرعی خاص در عناصر انتخاب شده باشد. شما این کار را با استفاده از نحو انتخاب فرعی " ( ) " مانند مثال های زیر انجام می دهید.
مثال ها اثر
entry/author(uri) فقط عنصر فرعی <uri> را برای نویسندگان در ورودی‌های فید برمی‌گرداند.
entry/author[name='Jo'](uri) فقط عنصر فرعی <uri> <author> برای هر ورودی که نام نویسنده 'Jo' دارد برمی‌گرداند.
entry(link(@rel, @href)) فقط مقادیر ویژگی‌های rel و href را برای هر عنصر <link> در ورودی‌های فید برمی‌گرداند.
entry(title,link[@rel='edit']) فقط عناصر <title> و <link> را با ویژگی‌های edit rel برای هر ورودی فید برمی‌گرداند.
entry(title,author(uri) هم عناصر <title> و هم عناصر نویسنده <uri> را برای هر ورودی فید برمی گرداند.

بیشتر در مورد نحو شرایط فیلد

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

مقدار متن فیلد انتخاب شده برای مقایسه استفاده می شود. در این زمینه، اگر فیلد یک عنصر باشد، مقدار متن محتوای آن است. اگر فیلد یک ویژگی باشد، مقدار متن، مقدار مشخصه است. If the field has no text value, then the comparison fails and the field is not included in the results.

The following table shows the XPath operators that are supported for field conditions and provides some examples.

Operator Syntax مثال ها
String comparison

= or eq
!= or ne

  • Returns entire entry if it contains a <link> element with an attribute rel set to ' self' :
    entry[link/@rel='self']

  • Returns entire entry if it contains a <title> element with content equal to the string 'unknown' :
    entry[title eq 'unknown']

  • Returns entire <title> element if its content is not 'unknown' :
    title[text() != 'unknown']
Logical comparison and
or
not
  • Returns any link that has an attribute rel set to 'self' or 'edit' :
    link[@rel='self' or @rel='edit']

  • Returns any link that has an attribute rel set to 'self' and an attribute type set to 'application/atom+xml' :
    link[@rel='self' and @type='application/atom+xml']

  • Returns any link that does not have an attribute rel with value 'self' :
    link[not(@rel='self')]

    Note that, as in XPath, not looks like a function call.
Numerical comparison = or eq
!= or ne
> or gt
> = or ge
< or lt
<= or le
  • Returns any <gd:rating> element with a value attribute that can be transformed into the integer 5:
    gd:rating[@value=5]

  • Returns any <gd:rating> element with an average attribute that can be transformed into a float that is bigger than 4.3 :
    gd:rating[@average gt 4.3]
Date comparison Use numerical comparison operators, as shown in examples.

To do date or date/time comparisons, you can cast elements, attributes, or string literals into xs:date or xs:dateTime . For xs:dateTime , the default timezone is UTC, but it is best to specify a timezone explicitly.

  • Returns any <yt:recorded> element that contains a date since Jan. 1, 2005:
    yt:recorded[xs:date(text())>=xs:date('2005-01-01')]

  • Returns any entries that were updated after the time given, specified in the UTC timezone:
    entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]
Existence

Use name of element or attribute as shown in examples.

  • Returns any entries that contain a link with an attribute rel :
    entry[link/@rel]

  • Returns any <gd:rating> elements that have an attribute called value :
    entry/gd:rating[@value]
بولی true()
 false()

Booleans can be useful during testing to force field conditions into a true or false state.

  • Returns any <link> elements:
    link[true()]

Handling partial responses

After a server that supports partial response processes a valid request that includes the fields query parameter, it sends back an HTTP 200 OK status code along with the requested attributes or elements. If the fields query parameter has an error or is otherwise invalid, the server returns an HTTP 400 Bad Request status code.

The root element of the response is either <feed> or <entry> , depending on the target URI. The root element's content includes only the selected fields for that feed or entry, along with the enclosing tags for any parent elements.

The value of the the request's fields query parameter can be echoed back in two ways:

  • The root element has a gd:fields attribute that shows value of the fields query parameter specified in the request.
  • If the target URI is a feed, each editable entry has a gd:fields attribute that shows the portion of the fields selection that applies to it.

Note: In order to see these gd:fields attribute values in your partial response, you must include them in your fields query parameter specification. You can do this explicitly, using @gd:fields , or using the more general @gd:* , which also includes ETag information.

The following example query asks the server to return a document that contains only attributes in the gd namespace (at both the feed and entry level), as well as the feed ID, the title, and the edit link for each feed entry:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

The server returns the following partial response, along with a 200 Successful HTTP status code:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

If the selected fields do not match anything, the service still returns a 200 Successful HTTP status code, but the partial response is an empty feed:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Partial update (Experimental)

Google products that support partial response and editable resources also allow you to use partial update . With partial update, you send only the fields you want to update, rather sending a modified version of the full resource representation. This lets your client application be more efficient when making updates, as well as when using partial response to retrieve data.

Instead of using PUT , however, you must use a PATCH request when making a partial update. The semantics for PATCH are powerful enough to let you add, replace, and delete specific fields for a particular entry, all with a single request.

To find out if partial update is available for the product you are using, refer to the product-specific documentation.

Submitting a partial update request

To submit a partial update request, you send an HTTP PATCH request to the same URL that you would normally use with PUT to update the resource. The body of the PATCH request is a partial <entry> element that specifies the fields you want to add or modify. The entry's gd:fields attribute indicates the fields you want to delete.

The server processes PATCH requests in a specific order:

  1. It first removes from the resource representation the fields specified by the gd:fields attribute.

    The syntax for the gd:fields attribute is the same as for the fields query parameter used when requesting a partial response. See Supported syntax for more details.

  2. It then merges into the existing resource representation the data provided in the body of the request.

    More details on how the data is merged are provided in Adding or updating fields below.

Note: Since the body of a PATCH request is not typically compliant with the Atom Syndication Format, the Content-Type you use with a PATCH request is application/xml .

Here is an example of a partial update request:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

This PATCH request makes the following changes to the resource representation stored on the server for the target URI's entry:

  • Removes the <description> element.
  • Updates the <title> element.

Semantics of a partial update request

The instructions below explain how to set up your PATCH request to delete, add, or update specific fields within an entry. A single PATCH request can perform any combination of these operations.

  • Deleting fields. Use the <entry> element's gd:fields attribute to identify any fields you want deleted from the resource. The following sample request deletes the title and summary associated with an entry. However the request does not add or update any other data for the entry.

    PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>

  • Adding or updating fields. Use the body of the <entry> element to specify the data that you want to add or update for a resource. These fields are merged into the existing data for the resource, after any deletions are made, according to the following rules:

    • Fields not already present are added. If the resource data does not already specify a value for a field, then the field is added to the existing data. For example, if an entry does not have a title, and your PATCH request contains a <title> element, then the new title is added to the entry.

    • Fields already present are replaced or appended. The specific behavior for merging fields that are already specified in the resource data depends on the characteristics of the field:

      • Non-repeating fields are replaced. If the resource data already specifies a value for a non-repeating element, then the value you specify in the PATCH request replaces the existing value for that element. For example, in the example below, the new title replaces the existing title.

        PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>

        A more complex example is given below. For this example, assume that the entry can have only one author, and that the target resource already has values for the author's name and email address. Even though <author> element has two child fields, only the <name> element is present in the data provided. As a result, only that field's value is overwritten. The value of the <email> element, which is missing from the data provided, remains unchanged.

        PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>

      • Repeating fields are appended. If the resource data already specifies a value for a repeating element, then the new element you provide is added to the existing set of values.

        Note that there might be times when you want to do something other than add a new instance of a repeating element. For example, you might want to do one of the following:

        • Replace an entire list of repeating elements. You can delete all the repeating fields using the gd:fields attribute ( gd:fields='ns:accessControl' , for example) and provide a complete set of the replacement fields. Since all the existing elements are deleted first, the set of fields you provide do not conflict with any existing values when they are appended.

        • Replace one value in a set of existing values for a repeating element. In this case, simply remove the single element by defining the gd:fields value narrowly enough to avoid deleting other values that you want to keep. For example, to remove only an access control with an action of embed , you might use gd:fields='ns:accessControl[@action="embed"]' . Then you provide the single field that you want to replace it with in the body of the <entry> element:

          PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>

Handling the response to a partial update

After processing a valid partial update request, the API returns a 200 OK HTTP response code. By default, the body of the response is the complete entry that you updated. The server updates ETag values when it successfully processes a PATCH request, just as it does with PUT .

If a PATCH request results in a new resource state that is syntactically or semantically invalid, the server returns an HTTP 400 Bad Request or 422 Unprocessable Entity HTTP status code, and the resource state remains unchanged. For example, if you attempt to delete a required field and do not provide a replacement, the server returns an error.

Note: It is important to understand how different fields relate to each other. It might be possible to put a resource into an inconsistent state by updating only part of mutually interdependent values. For example, it might be possible to update a start time to a later value than an end time. Although the API should return an error code, we recommend that you fully test these kinds of conditions to ensure consistency.

Alternate notation when PATCH is not supported

If your firewall does not allow PATCH , then do an HTTP POST request and set the override header to PATCH , as shown below:

POST /myfeed/1/1/
X-HTTP-Method-Override: PATCH
Content-Type: application/xml
...

Using partial response with partial update

You can use a partial response as the basis of a subsequent partial update request. If you do this, specify a fields query parameter that includes edit links, as well as @gd:* . This ensures that the partial response includes information like the ETag and gd:fields attribute values, which are important for subsequent requests.

Here is an example that returns a partial response that you could use as the basis for a future partial update:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

The server responds:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Suppose that you want to remove the user with email 'jane@gmail.com' , add a user with email 'will@gmail.com' , and change the email for the user currently listed as 'jo@gmail.com' to 'josy@gmail.com' .

You can make these changes simply by starting with the results of the previous response, modifying only the fields that are different, and submitting the modified partial entry as the body of the PATCH request. For this example, the needed modifications are:

  • Delete <gd:who email='jane'/> from the list of elements provided.
  • Add <gd:who email='will@gmail.com'/> to the list of elements provided.
  • Replace <gd:who email='jo@gmail.com'/> with <gd:who email='josy@gmail.com'/> .

The PATCH request based on the pevious partial response is shown below:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Note: This approach relies on the gd:fields and gd:etag (if supported) attributes being included in the partial response for the entry. The body of the partial entry must retain all fields and attribute that were present in the partial response — except for those you explicitly want to remove. You can update any of the existing fields in the body with new values, and you can include any new fields you want to add.

Authentication

When a client tries to access a service, it may need to provide the user's credentials to the service, to demonstrate that the user has the authority to perform the action in question.

The approach that a client should use for authentication depends on the type of client:

In the ClientLogin system, the desktop client asks the user for their credentials, and then sends those credentials to the Google authentication system.

If authentication succeeds, then the authentication system returns a token that the client subsequently uses (in an HTTP Authorization header) when it sends Data API requests.

If authentication fails, then the server returns a 403 Forbidden status code, along with a WWW-Authenticate header containing a challenge applicable to the authentication.

The AuthSub system works similarly, except that instead of asking the user for their credentials, it connects the user to a Google service that requests credentials. The service then returns a token that the web application can use; the advantage of this approach is that Google (rather than the web front end) securely handles and stores the user's credentials.

For details about these authentication systems, see the Google Data APIs Authentication Overview or the Google Account Authentication documentation.

Session state

Many business logic implementations require session stickiness—keeping track of the state of a user's session.

Google tracks session state in two ways: using cookies, and using a token that can be sent as a query parameter. Both methods achieve the same effect. We recommend that clients support one of these session-state tracking methods (either one is sufficient). If a client doesn't support either of these methods, then that client will still work with Data APIs, but performance may suffer compared to clients that do support these methods. Specifically, if a client doesn't support these methods, then every request results in a redirect, and therefore every request (and any associated data) is sent to the server twice, which affects the performance of both the client and the server.

The Google client libraries handle session state for you, so if you use our libraries, you don't have to do anything to get session state support.

Additional resources

You may find the following third-party documents useful:

Back to top