將用戶端與 Gmail 同步處理

本文說明如何透過 Gmail API 同步處理用戶端。

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

完整同步

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

如要執行完整同步，請按照下列步驟操作：

1. 呼叫 messages.list 方法，擷取第一頁的訊息 ID。

2. 為清單要求傳回的每則訊息建立 批次要求，其中包含 messages.get 方法要求。

   如果應用程式會顯示訊息內容，請在應用程式首次擷取訊息時，將 format 參數設為 format=full 或 format=raw，並快取結果，以免執行額外的擷取作業。如要擷取先前快取的訊息，請使用 format=minimal 縮減回應大小，因為只有 labelIds 可能會變更。

3. 將更新合併至快取結果。應用程式應儲存最新訊息 (list 回應中的第一則訊息) 的 historyId，以供日後進行部分同步。

注意： 您也可以使用對應的 threads 方法執行完整同步作業。如果應用程式主要處理訊息串，或只需要訊息中繼資料，這項做法可能會有優勢。

部分同步

如果應用程式最近已同步處理，您可以使用 history.list 方法執行部分同步處理，傳回所有新於 startHistoryId 查詢參數的記錄。您必須在要求中指定該參數。

startHistoryId 查詢參數必須設為最近一則訊息的 historyId。如要擷取最近一則訊息的 historyId，請使用 messages.get 或 messages.list 方法。您也可以在完整或部分同步處理期間設定值，以供日後使用。

傳回的 History 物件包含訊息 ID，以及自提供的 startHistoryId 時間以來，每則訊息的變更類型，例如新增訊息或修改標籤。

限制

記錄通常會保留至少一週，有時會更久。 不過，記錄的可用時間範圍可能會大幅縮短，而且在極少數情況下，記錄可能無法使用。

如果用戶端提供的 startHistoryId 超出可用記錄範圍，Gmail API 會傳回 HTTP 404 錯誤回應。在這種情況下，客戶必須執行完整同步。