同步處理用戶端與 Gmail

在大多數應用程式情境中，讓用戶端與 Gmail 保持同步非常重要。整體同步處理有兩種情況：完整同步處理和部分同步處理。當用戶端首次連線至 Gmail 或在其他罕見情況下，就必須進行完整同步處理。如果您的用戶端最近已同步，則部分同步處理是比完整同步處理更輕量化的替代方案。您也可以使用推播通知，在需要時即時觸發部分同步處理，避免不必要的輪詢。

目錄

完整同步處理

應用程式首次連線至 Gmail，或無法進行部分同步處理時，您必須執行完整同步處理。在完整同步作業中，應用程式應擷取及儲存所需的最新訊息或執行緒。舉例來說，如果應用程式顯示最近的訊息清單，您可能會想要擷取並快取足夠的訊息，以便在使用者捲動至顯示的前幾則訊息後，提供回應式介面。執行完整同步作業的一般程序如下：

1. 呼叫 messages.list 以擷取第一頁的訊息 ID。
2. 針對清單要求傳回的每則訊息，建立 批次要求的 messages.get 要求。如果應用程式會顯示訊息內容，請在應用程式第一次擷取訊息時使用 format=FULL 或 format=RAW，並將結果快取，以免執行額外的擷取作業。如果您要擷取先前快取的訊息，請使用 format=MINIMAL 來縮減回應大小，因為只有 labelIds 可能會變更。
3. 將更新內容合併至快取結果。應用程式應儲存最新訊息的 historyId (list 回應中的首則訊息)，以利日後進行部分同步處理。

注意： 您也可以使用等同的 Threads 資源方法執行同步處理作業。如果您的應用程式主要使用執行緒，或只需要訊息中繼資料，這可能會是較佳的做法。

部分同步處理

如果應用程式最近已同步，您可以使用 history.list 方法執行部分同步作業，藉此傳回比您在要求中指定的 startHistoryId 更新的所有歷史記錄。記錄記錄會提供每封郵件的郵件 ID 和變更類型，例如自 startHistoryId 以來新增、刪除或修改的郵件標籤。您可以從完整或部分同步處理中取得並儲存最新訊息的 historyId，並將其做為 startHistoryId 提供給日後的部分同步處理作業。

限制

歷史記錄通常會保留至少一週，有時更久。不過，記錄可供查詢的時間可能會大幅縮短，且在極少數情況下，記錄可能無法提供。如果用戶端提供的 startHistoryId 超出歷史記錄可用範圍，API 會傳回 HTTP 404 錯誤回應。在這種情況下，您的用戶端必須執行完整的同步處理，如上一節所述。