Koleksiyonlar ile düzeninizi koruyun
İçeriği tercihlerinize göre kaydedin ve kategorilere ayırın.
Çoğu uygulama senaryosunda istemcinizin Gmail ile senkronize kalması önemlidir. Genel olarak iki senkronizasyon senaryosu vardır: tam senkronizasyon ve kısmi senkronizasyon. İstemciniz Gmail'e ilk kez bağlandığında ve bazı nadir durumlarda tam senkronizasyon gerekir. Müşteriniz yakın zamanda senkronizasyon yaptıysa kısmi senkronizasyon, tam senkronizasyona kıyasla daha az kaynak kullanan bir alternatiftir. Ayrıca, anlık bildirimleri kullanarak kısmi senkronizasyonu yalnızca gerektiğinde ve gerçek zamanlı olarak tetikleyebilir, böylece gereksiz yoklamaları önleyebilirsiniz.
İçindekiler
Tam senkronizasyon
Uygulamanız Gmail'e ilk kez bağlandığında veya kısmi senkronizasyon kullanılamadığında tam senkronizasyon yapmanız gerekir. Tam senkronizasyon işleminde uygulamanız, amacınız için gerekli olan en yeni mesajları veya ileti dizilerini alıp depolamalıdır. Örneğin, uygulamanızda son mesajların listesi gösteriliyorsa kullanıcının gösterilen ilk birkaç mesajın ötesine kaydırması durumunda duyarlı bir arayüz sağlamak için yeterli sayıda mesajı alıp önbelleğe almak isteyebilirsiniz. Tam senkronizasyon işlemi gerçekleştirme prosedürü genel olarak şu şekildedir:
İleti kimliklerinin ilk sayfasını almak için messages.list işlevini çağırın.
Liste isteği tarafından döndürülen iletilerin her biri için toplu istek oluşturun. Bu toplu istek, messages.get isteklerinden oluşur. Uygulamanız ileti içeriklerini gösteriyorsa uygulamanız bir iletiyi ilk kez aldığında format=FULL veya format=RAW kullanmalı ve ek alma işlemlerini önlemek için sonuçları önbelleğe almalıdır. Daha önce önbelleğe alınmış bir iletiyi alıyorsanız yalnızca labelIds değişebileceğinden yanıtın boyutunu küçültmek için format=MINIMAL kullanmanız gerekir.
Güncellemeleri önbelleğe alınmış sonuçlarınızla birleştirin. Uygulamanız, gelecekteki kısmi senkronizasyon için en son mesajın historyId değerini (list yanıtındaki ilk mesaj) saklamalıdır.
Kısmi senkronizasyon
Uygulamanız yakın zamanda senkronize edildiyse isteğinizde belirttiğiniz startHistoryId tarihinden daha yeni olan tüm geçmiş kayıtlarını döndürmek için history.list yöntemini kullanarak kısmi senkronizasyon gerçekleştirebilirsiniz. Geçmiş kayıtları, startHistoryId zamanından itibaren eklenen, silinen veya etiketleri değiştirilen iletiler gibi her ileti için ileti kimliklerini ve değişiklik türünü sağlar. Gelecekteki kısmi senkronizasyon işlemleri için startHistoryId olarak sağlamak üzere tam veya kısmi senkronizasyondan en son mesajın historyId bilgisini alıp saklayabilirsiniz.
Sınırlamalar
Geçmiş kayıtları genellikle en az bir hafta, çoğu zaman da daha uzun süre kullanılabilir. Ancak kayıtların kullanılabildiği süre önemli ölçüde daha kısa olabilir ve nadir durumlarda kayıtlar kullanılamayabilir. Müşteriniz tarafından sağlanan startHistoryId, mevcut geçmiş kayıtları aralığının dışındaysa API, HTTP 404 hata yanıtı döndürür. Bu durumda, müşteriniz önceki bölümde açıklandığı gibi tam senkronizasyon gerçekleştirmelidir.
[null,null,["Son güncelleme tarihi: 2025-08-29 UTC."],[],[],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."]]
