مروری بر راهنمای توسعه‌دهنده

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

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

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

حضار

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

اگر به دنبال راهنمای برنامه‌نویس برای یک API خاص هستید، از فهرست API پروتکل داده Google دیدن کنید.

اگر می خواهید به یک API در زبان برنامه نویسی مورد علاقه خود دسترسی داشته باشید، از صفحه دانلود Client Libraries دیدن کنید.

زمینه

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

توجه: محصولات Google که API ارائه می کنند، گاهی اوقات در این اسناد و سایر اسناد مرتبط به عنوان خدمات نامیده می شوند.

اگر کدی بنویسید که مستقیماً از پروتکل داده Google استفاده می کند، با استفاده از درخواست های HTTP مانند GET یا POST به API دسترسی پیدا می کند. با این درخواست‌ها، داده‌های ذخیره‌شده توسط محصول Google به صورت فید داده از طریق سیم به عقب و جلو منتقل می‌شوند. فیدهای داده به سادگی لیست های ساختاری هستند که حاوی داده ها هستند. از لحاظ تاریخی، فرمت اصلی فید AtomPub XML بوده است، اما اکنون JSON یا JavaScript Object Notation نیز به عنوان یک فرمت جایگزین در دسترس است.

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

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

نسخه های پروتکل

نسخه پروتکل 2.0 در مقابل پروتکل نسخه 1.0

اولین نسخه از پروتکل داده گوگل قبل از نهایی شدن پروتکل انتشار اتم توسعه یافت. نسخه دوم پروتکل داده گوگل کاملاً با استاندارد AtomPub RFC 5023 مطابقت دارد.

Google Data Protocol نسخه 2.0 همچنین شامل پشتیبانی از موارد زیر است:

• HTTP ETags یک استاندارد وب که به برنامه های مشتری شما کمک می کند تا از حافظه پنهان HTTP بهتر استفاده کنند. سرویس‌های موجود در کتابخانه‌های سرویس گیرنده که از Protocol v2.0 پشتیبانی می‌کنند، ETag‌ها را به‌طور خودکار مدیریت می‌کنند.
• پاسخ بخشی و به روز رسانی جزئی (تجربی) . ویژگی هایی که به شما امکان می دهد درخواست هایی ارسال کنید که داده های کمتری را منتقل می کند. با درخواست تنها اطلاعاتی که واقعاً نیاز دارید، یا با ارسال به‌روزرسانی‌هایی که فقط شامل داده‌هایی می‌شوند که واقعاً می‌خواهید تغییر دهید، برنامه مشتری شما می‌تواند در استفاده از شبکه، CPU و منابع حافظه بسیار کارآمدتر باشد. در حال حاضر، پاسخ جزئی و به روز رسانی جزئی فقط برای برخی از محصولات موجود است. برای اطلاع از اینکه آیا API شما از آن پشتیبانی می کند یا خیر، به مستندات محصول خاص مراجعه کنید.

در حال به روز رسانی برنامه شما

اگر API مورد استفاده شما بر اساس آخرین نسخه پروتکل ساخته شده است، عملکرد Protocol v2.0 در مستندات آن گنجانده شده است. به طور کلی، توصیه می کنیم که برنامه مشتری خود را به آخرین نسخه موجود برای API خود ارتقا دهید.

به روز رسانی یک سرویس گیرنده مبتنی بر کتابخانه-کلینت

اگر برنامه سرویس گیرنده شما از کتابخانه سرویس گیرنده استفاده می کند، مانند کتابخانه سرویس گیرنده جاوا یا کتابخانه سرویس گیرنده دات نت، ممکن است حاوی نسخه ای از API باشد که از ویژگی های Protocol v2.0 پشتیبانی می کند. برای اطلاع از این موضوع، به اسناد API محصول Google که استفاده می‌کنید مراجعه کنید تا از صحت هر دو مورد زیر مطلع شوید:

• یک نسخه API وجود دارد که از ویژگی های Google Data Protocol v2.0 پشتیبانی می کند.
• کتابخانه سرویس گیرنده ای که استفاده می کنید نیز از آن نسخه API پشتیبانی می کند.

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

به روز رسانی یک سرویس گیرنده HTTP خام

اگر برنامه مشتری خود را مستقیماً با استفاده از پروتکل داده Google نوشته اید، باید این تغییرات را انجام دهید:

• درخواست های نسخه غیر پیش فرض یک سرصفحه نسخه HTTP ( GData-Version: X .0 ) را به هر درخواست HTTP که ارسال می کنید اضافه کنید، جایی که X نسخه API است که از ویژگی های Google Data Protocol نسخه 2.0 پشتیبانی می کند. از طرف دیگر، یک پارامتر پرس و جو ( v= X .0 ) را به URL هر درخواست اضافه کنید، جایی که X دوباره نسخه صحیح API است. اگر نسخه بعدی را مشخص نکنید، درخواست های شما به طور پیش فرض به اولین نسخه پشتیبانی شده از API ارسال می شود.
• همزمانی خوش بینانه اگر از نسخه‌ای از یک API استفاده می‌کردید که از همزمانی خوش‌بینانه پشتیبانی می‌کرد، ممکن است لازم باشد به‌روزرسانی خود را تغییر دهید و کد را برای استفاده از ETags حذف کنید. برای اطلاعات بیشتر، بخش ETags اسناد مرجع پروتکل داده Google را بخوانید و بخش‌های به‌روزرسانی و حذف راهنمای توسعه‌دهنده پروتکل را برای سرویسی که برنامه مشتری شما استفاده می‌کند، بخوانید.
• URI ها را خودتان یا ویرایش کنید. اگر مشتری شما URI های خود را برای فیدها یا ورودی ها ردیابی می کند یا URI را ویرایش می کند، توجه داشته باشید که این URI ها ممکن است تغییر کرده باشند. برای دریافت URI جدید، مورد را با استفاده از URI قدیمی دوباره درخواست کنید، اما درخواست را به عنوان درخواست نسخه X .0 علامت گذاری کنید، جایی که X نسخه API است که از ویژگی های Google Data Protocol v2.0 پشتیبانی می کند. سرور نمایش جدید ورودی شامل URI های جدید را برمی گرداند که می توانید آنها را به جای URI های قدیمی ذخیره کنید.
• URI های فضای نام اگر مشتری شما URI های فضای نام API پروتکل داده Google را به صورت محلی ذخیره می کند، یا آنها را به صورت سخت کدگذاری کرده است، باید آنها را به روز کنید:
  • فضای نام AtomPub ( app پیشوند) از http://purl.org/atom/app به http://www.w3.org/2007/app تغییر کرده است.
  • فضای نام OpenSearch (پیشوند openSearch ) از http://a9.com/-/spec/opensearchrss/1.0/ به http://a9.com/-/spec/opensearch/1.1/ تغییر یافته است.