このドキュメントでは、Gmail API を使用してクライアントを同期する方法について説明します。
ほとんどのアプリ シナリオでは、クライアントを Gmail と同期することが重要です。同期方法には、フル同期と部分同期の 2 つがあります。クライアントが Gmail に初めて接続するときや、その他のまれなシナリオでは、完全な同期が必要です。クライアントが最近同期した場合は、部分同期はフル同期よりも軽量な代替手段となります。プッシュ通知を使用して、必要なときにのみリアルタイムで部分同期をトリガーすることもできます。これにより、不要なポーリングを回避できます。
完全同期
アプリが Gmail に初めて接続する場合、または部分同期が利用できない場合は、完全同期を実行する必要があります。完全同期オペレーションでは、アプリは目的のために必要な数の最新のメッセージまたはスレッドを取得して保存する必要があります。たとえば、アプリに最近のメッセージのリストが表示される場合、ユーザーが最初に表示された数件のメッセージを超えてスクロールしたときに、応答性の高いインターフェースを実現するために十分なメッセージを取得してキャッシュに保存することが望ましいでしょう。
フル同期を行う手順は次のとおりです。
messages.listメソッドを呼び出して、メッセージ ID の最初のページを取得します。リスト リクエストで返された各メッセージに対して、
messages.getメソッド リクエストのバッチ リクエストを作成します。アプリでメッセージの内容を表示する場合は、アプリが初めてメッセージを取得するときに
Formatをformat=FULLまたはformat=RAWに設定し、結果をキャッシュに保存して、追加の取得オペレーションを回避する必要があります。以前にキャッシュに保存されたメッセージを取得する場合は、format=MINIMALを使用してレスポンスのサイズを小さくする必要があります。これは、labelIdsのみが変更される可能性があるためです。更新をキャッシュに保存されている結果にマージします。アプリは、今後の部分同期のために、最新のメッセージの
historyId（listレスポンスの最初のメッセージ）を保存する必要があります。
部分同期
アプリが最近同期された場合は、history.list メソッドを使用して部分同期を実行し、リクエストで指定する必要がある startHistoryId クエリ パラメータよりも新しいすべての履歴レコードを返します。
startHistoryId クエリ パラメータは、最近のメッセージの historyId に設定する必要があります。最近のメッセージの historyId を取得するには、messages.get メソッドまたは messages.list メソッドを使用します。完全同期または部分同期中に値を設定して、後で使用することもできます。
返される History オブジェクトには、指定された startHistoryId 以降のメッセージ ID と、メッセージの追加やラベルの変更など、各メッセージの変更タイプが含まれます。
制限事項
通常、履歴レコードは少なくとも 1 週間、多くの場合それ以上利用できます。ただし、記録が利用可能な期間は大幅に短くなる可能性があり、まれに記録が利用できないことがあります。
クライアントから提供された startHistoryId が履歴レコードの利用可能な範囲外にある場合、Gmail API は HTTP 404 エラー レスポンスを返します。この場合、クライアントは完全な同期を実行する必要があります。