تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تُعدّ مزامنة تطبيقك مع Gmail أمرًا مهمًا في معظم سيناريوهات التطبيقات. هناك سيناريوهان عامّان للمزامنة: المزامنة الكاملة والمزامنة الجزئية. يجب إجراء مزامنة كاملة في المرة الأولى التي يتصل فيها برنامج البريد الإلكتروني الخاص بك بخدمة Gmail وفي بعض السيناريوهات النادرة الأخرى. إذا تمت مزامنة جهازك مؤخرًا، تكون المزامنة الجزئية بديلاً أخف وزنًا للمزامنة الكاملة. يمكنك أيضًا استخدام الإشعارات الفورية لتفعيل المزامنة الجزئية في الوقت الفعلي وعند الضرورة فقط، وبالتالي تجنُّب عمليات البحث غير الضرورية.
المحتويات
المزامنة الكاملة
في المرة الأولى التي يتصل فيها تطبيقك بخدمة Gmail، أو إذا لم تكن المزامنة الجزئية متاحة، عليك إجراء مزامنة كاملة. في عملية المزامنة الكاملة، يجب أن يسترد تطبيقك ويخزّن أكبر عدد ممكن من أحدث الرسائل أو سلاسل المحادثات اللازمة لتحقيق الغرض. على سبيل المثال، إذا كان تطبيقك يعرض قائمة بالرسائل الحديثة، قد تحتاج إلى استرداد وتخزين عدد كافٍ من الرسائل مؤقتًا للسماح بواجهة سريعة الاستجابة إذا انتقل المستخدم إلى ما بعد الرسائل القليلة الأولى المعروضة. في ما يلي الإجراء العام لتنفيذ عملية مزامنة كاملة:
اتّصِل بـ messages.list لاسترداد الصفحة الأولى من أرقام تعريف الرسائل.
أنشئ طلبًا مجمّعًا من طلبات messages.get لكل رسالة من الرسائل التي تم إرجاعها من خلال طلب القائمة. إذا كان تطبيقك يعرض محتوى الرسائل، عليك استخدام format=FULL أو format=RAW في المرة الأولى التي يسترد فيها تطبيقك رسالة، وتخزين النتائج مؤقتًا لتجنُّب عمليات استرداد إضافية. إذا كنت تسترجع رسالة تم تخزينها مؤقتًا من قبل، عليك استخدام format=MINIMAL لتقليل حجم الردّ لأنّ labelIds هو الجزء الوحيد الذي قد يتغيّر.
ادمج التعديلات في النتائج المخزّنة مؤقتًا. يجب أن يخزّن تطبيقك historyId أحدث رسالة (الرسالة الأولى في استجابة list) لإجراء مزامنة جزئية في المستقبل.
المزامنة الجزئية
إذا تمت مزامنة تطبيقك مؤخرًا، يمكنك إجراء مزامنة جزئية باستخدام طريقة history.list لعرض جميع سجلّات المحفوظات الأحدث من startHistoryId الذي تحدّده في طلبك. توفّر سجلّات السجلّ أرقام تعريف الرسائل ونوع التغيير لكل رسالة، مثل الرسالة التي تمت إضافتها أو حذفها أو تعديل تصنيفاتها منذ وقت startHistoryId. يمكنك الحصول على historyId لأحدث رسالة وتخزينها من خلال مزامنة كاملة أو جزئية لاستخدامها كـ startHistoryId لعمليات المزامنة الجزئية المستقبلية.
القيود
تتوفّر سجلّات السجلّ عادةً لمدة أسبوع واحد على الأقل، وغالبًا ما تكون المدة أطول. ومع ذلك، قد تكون الفترة الزمنية التي تتوفّر فيها السجلات أقل بكثير، وقد لا تتوفّر السجلات أحيانًا في حالات نادرة. إذا كان startHistoryId الذي يقدّمه العميل خارج النطاق المتاح لسجلات السجلّ، ستعرض واجهة برمجة التطبيقات استجابة خطأ 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."]]
