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