این سند نحوه همگامسازی کلاینتها با 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 را برمیگرداند. در این حالت، کلاینت شما باید همگامسازی کامل را انجام دهد.