با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
همگام نگه داشتن مشتری شما با Gmail برای اکثر سناریوهای برنامه مهم است. دو سناریو همگام سازی کلی وجود دارد: همگام سازی کامل و همگام سازی جزئی. اولین باری که مشتری شما به Gmail وصل می شود و در برخی از حالات نادر دیگر، همگام سازی کامل لازم است. اگر مشتری شما اخیراً همگام‌سازی شده است، همگام‌سازی جزئی یک جایگزین سبک‌تر برای همگام‌سازی کامل است. همچنین می‌توانید از اعلان‌های فشاری برای راه‌اندازی همگام‌سازی جزئی در زمان واقعی و تنها در مواقع ضروری استفاده کنید، بنابراین از نظرسنجی بی‌ضرور اجتناب کنید.
مطالب
همگام سازی کامل
اولین باری که برنامه شما به Gmail متصل می شود، یا اگر همگام سازی جزئی در دسترس نیست، باید همگام سازی کامل انجام دهید. در یک عملیات همگام‌سازی کامل، برنامه شما باید هر تعداد از پیام‌ها یا رشته‌های اخیر را که برای هدف شما ضروری است، بازیابی و ذخیره کند. برای مثال، اگر برنامه شما فهرستی از پیام‌های اخیر را نمایش می‌دهد، ممکن است بخواهید پیام‌های کافی را بازیابی و ذخیره کنید تا اگر کاربر فراتر از چند پیام اول نمایش داده شده حرکت کند، یک رابط پاسخگو را فراهم کند. روش کلی برای انجام عملیات همگام سازی کامل به شرح زیر است:
برای بازیابی صفحه اول شناسه پیام، messages.list را فراخوانی کنید.
یک درخواست دسته ای از درخواست messages.get برای هر یک از پیام های بازگردانده شده توسط درخواست لیست ایجاد کنید. اگر برنامه شما محتویات پیام را نمایش می دهد، باید از format=FULL یا format=RAW اولین باری که برنامه شما پیامی را بازیابی می کند استفاده کنید و نتایج را در حافظه پنهان نگه دارید تا از عملیات بازیابی اضافی جلوگیری شود. اگر در حال بازیابی یک پیام ذخیره شده قبلی هستید، باید از format=MINIMAL برای کاهش اندازه پاسخ استفاده کنید زیرا فقط labelIds ممکن است تغییر کند.
به روز رسانی ها را در نتایج ذخیره شده خود ادغام کنید. برنامه شما باید historyId آخرین پیام (اولین پیام در پاسخ list ) را برای همگام سازی جزئی در آینده ذخیره کند.
همگام سازی جزئی
اگر برنامه شما اخیراً همگام‌سازی شده است، می‌توانید با استفاده از روش history.list یک همگام‌سازی جزئی انجام دهید تا تمام رکوردهای سابقه جدیدتر از startHistoryId که در درخواست خود مشخص کرده‌اید بازگردانید. سوابق سابقه شناسه‌های پیام و نوع تغییر را برای هر پیام ارائه می‌کنند، مانند پیام‌هایی که از زمان startHistoryId اضافه شده، حذف شده‌اند، یا برچسب‌هایی اصلاح شده‌اند. می‌توانید historyId جدیدترین پیام را از یک همگام‌سازی کامل یا جزئی دریافت و ذخیره کنید تا به‌عنوان startHistoryId برای عملیات همگام‌سازی جزئی در آینده ارائه شود.
محدودیت ها
سوابق تاریخ معمولاً حداقل برای یک هفته و اغلب بیشتر در دسترس هستند. با این حال، دوره زمانی که برای آن سوابق موجود است ممکن است به میزان قابل توجهی کمتر باشد و گاهی اوقات ممکن است در موارد نادر سوابق در دسترس نباشد. اگر startHistoryId ارائه شده توسط مشتری شما خارج از محدوده موجود رکوردهای سابقه باشد، API یک پاسخ خطای HTTP 404 را برمی‌گرداند. در این مورد، مشتری شما باید یک همگام سازی کامل را همانطور که در بخش قبل توضیح داده شد انجام دهد.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Synchronizing Clients with Gmail\n\nKeeping your client synchronized with Gmail is important for most application\nscenarios. There are two overall synchronization scenarios: full synchronization\nand partial synchronization. Full synchronization is required the first time\nyour client connects to Gmail and in some other rare scenarios. If your client\nhas recently synchronized, partial synchronization is a lighter-weight\nalternative to a full sync. You can also use [push notifications](/workspace/gmail/api/guides/push)\nto trigger partial synchronization in real-time and only when necessary, thereby\navoiding needless polling.\n\nContents\n--------\n\nFull synchronization\n--------------------\n\nThe first time your application connects to Gmail, or if partial synchronization\nis not available, you must perform a full sync. In a full sync operation, your\napplication should retrieve and store as many of the most recent messages or\nthreads as are necessary for your purpose. For example, if your application\ndisplays a list of recent messages, you may wish to retrieve and cache enough\nmessages to allow for a responsive interface if the user scrolls beyond the\nfirst several messages displayed. The general procedure for performing a full\nsync operation is as follows:\n\n1. Call [`messages.list`](/workspace/gmail/api/v1/reference/users/messages/list) to retrieve the first page of message IDs.\n2. Create a [batch request](/workspace/gmail/api/guides/batch) of [`messages.get`](/workspace/gmail/api/v1/reference/users/messages/get) requests for each of the messages returned by the list request. If your application displays message contents, you should use `format=FULL` or `format=RAW` the first time your application retrieves a message and cache the results to avoid additional retrieval operations. If you are retrieving a previously cached message, you should use `format=MINIMAL` to reduce the size of the response as only the `labelIds` may change.\n3. Merge the updates into your cached results. Your application should store the `historyId` of the most recent message (the first message in the `list` response) for future partial synchronization.\n\n| **Note:** You can also perform synchronization using the equivalent [`Threads` resource](/workspace/gmail/api/v1/reference/users/threads) methods. This may be advantageous if your application primarily works with threads or only requires message metadata.\n\nPartial synchronization\n-----------------------\n\nIf your application has synchronized recently, you can perform a partial\nsync using the [`history.list`](/workspace/gmail/api/v1/reference/users/history/list)\nmethod to return all history records newer than the `startHistoryId` you specify\nin your request. History records provide message IDs and type of change for\neach message, such as message added, deleted, or labels modified since the time\nof the `startHistoryId`. You can obtain and store the `historyId` of the most\nrecent message from a full or partial sync to provide as a `startHistoryId` for\nfuture partial synchronization operations.\n\nLimitations\n-----------\n\nHistory records are typically available for at least one week and often\nlonger. However, the time period for which records are available may be\nsignificantly less and records may sometimes be unavailable in rare cases. If\nthe `startHistoryId` supplied by your client is outside the available range of\nhistory records, the API returns an `HTTP 404` error response. In this case,\nyour client must perform a full sync as described in the previous section."]]
