このドキュメントでは、クライアントを 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 エラー レスポンスを返します。この場合、クライアントは完全な同期を実行する必要があります。