همگامسازی کلاینت با جیمیل برای اکثر سناریوهای برنامه مهم است. دو سناریوی کلی همگامسازی وجود دارد: همگامسازی کامل و همگامسازی جزئی. همگامسازی کامل در اولین اتصال کلاینت به جیمیل و در برخی سناریوهای نادر دیگر مورد نیاز است. اگر کلاینت شما اخیراً همگامسازی کرده باشد، همگامسازی جزئی جایگزین سبکتری برای همگامسازی کامل است. همچنین میتوانید از اعلانهای فوری برای فعال کردن همگامسازی جزئی در زمان واقعی و فقط در صورت لزوم استفاده کنید و از این طریق از نظرسنجی غیرضروری جلوگیری کنید.
فهرست مطالب
همگامسازی کامل
اولین باری که برنامه شما به Gmail متصل میشود، یا اگر همگامسازی جزئی در دسترس نباشد، باید همگامسازی کامل را انجام دهید. در یک عملیات همگامسازی کامل، برنامه شما باید تا حد امکان از جدیدترین پیامها یا رشتهها که برای هدف شما ضروری است، بازیابی و ذخیره کند. به عنوان مثال، اگر برنامه شما لیستی از پیامهای اخیر را نمایش میدهد، ممکن است بخواهید پیامهای کافی را بازیابی و ذخیره کنید تا در صورت پیمایش کاربر فراتر از چند پیام اول نمایش داده شده، رابط کاربری پاسخگو باشد. روش کلی برای انجام عملیات همگامسازی کامل به شرح زیر است:
- برای بازیابی صفحه اول شناسههای پیام، تابع
messages.listرا فراخوانی کنید. - یک درخواست دستهای از
messages.getrequest برای هر یک از پیامهای برگردانده شده توسط درخواست لیست ایجاد کنید. اگر برنامه شما محتوای پیام را نمایش میدهد، بایدformat=FULLیاformat=RAWبرای اولین باری که برنامه شما پیامی را بازیابی میکند استفاده کنید و نتایج را ذخیره کنید تا از عملیات بازیابی اضافی جلوگیری شود. اگر در حال بازیابی پیامی هستید که قبلاً ذخیره شده است، بایدformat=MINIMALبرای کاهش اندازه پاسخ استفاده کنید زیرا فقطlabelIdsممکن است تغییر کنند. - بهروزرسانیها را در نتایج ذخیرهشدهی خود ادغام کنید. برنامهی شما باید
historyIdجدیدترین پیام (اولین پیام درlistپاسخ) را برای همگامسازی جزئی در آینده ذخیره کند.
همگامسازی جزئی
اگر برنامه شما اخیراً همگامسازی شده است، میتوانید با استفاده از متد history.list یک همگامسازی جزئی انجام دهید تا تمام رکوردهای تاریخچه جدیدتر از startHistoryId که در درخواست خود مشخص کردهاید را برگردانید. رکوردهای تاریخچه، شناسههای پیام و نوع تغییر برای هر پیام، مانند پیام اضافه شده، حذف شده یا برچسبهای تغییر یافته از زمان startHistoryId را ارائه میدهند. میتوانید historyId جدیدترین پیام را از یک همگامسازی کامل یا جزئی دریافت و ذخیره کنید تا به عنوان startHistoryId برای عملیات همگامسازی جزئی آینده ارائه دهید.
محدودیتها
رکوردهای تاریخچه معمولاً حداقل برای یک هفته و اغلب بیشتر در دسترس هستند. با این حال، مدت زمانی که رکوردها در دسترس هستند ممکن است به طور قابل توجهی کمتر باشد و گاهی اوقات در موارد نادر، رکوردها در دسترس نباشند. اگر startHistoryId ارائه شده توسط کلاینت شما خارج از محدوده موجود رکوردهای تاریخچه باشد، API پاسخ خطای HTTP 404 را برمیگرداند. در این حالت، کلاینت شما باید همگامسازی کامل را همانطور که در بخش قبلی توضیح داده شد، انجام دهد.