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