클라이언트를 Gmail과 동기화하는 것은 대부분의 애플리케이션 시나리오에서 중요합니다. 전체 동기화와 부분 동기화라는 두 가지 전체 동기화 시나리오가 있습니다. 클라이언트가 Gmail에 처음 연결될 때와 드문 다른 시나리오에서는 전체 동기화가 필요합니다. 클라이언트가 최근에 동기화된 경우 부분 동기화는 전체 동기화보다 가벼운 대안입니다. 푸시 알림을 사용하여 필요할 때만 실시간으로 부분 동기화를 트리거하여 불필요한 폴링을 방지할 수도 있습니다.
목차
전체 동기화
애플리케이션이 Gmail에 처음 연결되거나 부분 동기화를 사용할 수 없는 경우 전체 동기화를 실행해야 합니다. 전체 동기화 작업에서 애플리케이션은 목적에 필요한 만큼의 최신 메시지나 스레드를 검색하고 저장해야 합니다. 예를 들어 애플리케이션에 최근 메시지 목록이 표시되는 경우 사용자가 표시된 처음 몇 개의 메시지를 지나 스크롤할 때 반응형 인터페이스를 지원할 수 있도록 충분한 메시지를 가져와 캐시할 수 있습니다. 전체 동기화 작업을 실행하는 일반적인 절차는 다음과 같습니다.
목록 요청에서 반환된 각 메시지에 대해 messages.get 요청의 일괄 요청을 만듭니다. 애플리케이션이 메시지 콘텐츠를 표시하는 경우 애플리케이션이 처음 메시지를 가져올 때 format=FULL 또는 format=RAW를 사용하고 추가 검색 작업을 방지하기 위해 결과를 캐시해야 합니다. 이전에 캐시된 메시지를 가져오는 경우 labelIds만 변경될 수 있으므로 format=MINIMAL를 사용하여 응답 크기를 줄여야 합니다.
업데이트를 캐시된 결과에 병합합니다. 애플리케이션은 향후 부분 동기화를 위해 최신 메시지의 historyId (list 응답의 첫 번째 메시지)를 저장해야 합니다.
부분 동기화
애플리케이션이 최근에 동기화된 경우 history.list 메서드를 사용하여 요청에 지정한 startHistoryId보다 최신인 모든 기록 레코드를 반환하는 부분 동기화를 실행할 수 있습니다. 기록 레코드에는 startHistoryId 이후 메시지 추가, 삭제, 라벨 수정 등 각 메시지의 메시지 ID와 변경 유형이 제공됩니다. 전체 또는 부분 동기화에서 최신 메시지의 historyId를 가져와 저장하여 향후 부분 동기화 작업의 startHistoryId로 제공할 수 있습니다.
제한사항
기록은 일반적으로 최소 1주일 동안 제공되며 그 이상인 경우도 많습니다. 하지만 기록을 사용할 수 있는 기간이 훨씬 짧을 수 있으며 드물게 기록을 사용할 수 없는 경우도 있습니다. 클라이언트에서 제공한 startHistoryId이 사용 가능한 기록 범위 밖에 있는 경우 API는 HTTP 404 오류 응답을 반환합니다. 이 경우 클라이언트는 이전 섹션에 설명된 대로 전체 동기화를 실행해야 합니다.
[null,null,["최종 업데이트: 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."]]
