同步處理用戶端與 Gmail

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

目錄

完整同步

應用程式首次連線至 Gmail 時，或如果無法進行部分同步，您必須執行完整同步。在完整同步作業中，應用程式應擷取並儲存盡可能多的最新訊息或討論串，以滿足您的需求。舉例來說，如果應用程式顯示最近的訊息清單，您可能希望擷取並快取足夠的訊息，讓使用者捲動超過顯示的前幾則訊息時，介面仍能保持回應。執行完整同步作業的一般程序如下：

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

注意： 您也可以使用對應的 Threads 資源方法執行同步作業。如果應用程式主要處理討論串，或只需要訊息中繼資料，這項功能可能就很有用。

部分同步

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

限制

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