最良の結果を得るためのベスト プラクティス

Google Docs API を使用する際には、いくつかの原則に従う必要があります。 指標には以下が含まれます。

  • 逆方向編集で効率を上げる
  • コラボレーションの計画
  • WriteControl フィールドを使用して状態の整合性を確保する

以降のセクションでは、これらの原則について説明します。

逆方向編集で効率を上げる

documents.batchUpdate メソッドの 1 回の呼び出しで、インデックス位置の降順にリクエストを並べ替えます。これにより、挿入と削除によるインデックスの変更を計算する必要がなくなります。

コラボレーションの計画

ドキュメントの状態が変わることが想定されます。次の図に示すように、メソッド呼び出し間で、他の共同編集者がドキュメントを更新する場合があります。

メソッド呼び出し間でドキュメントが変更される方法。

インデックスが間違っていると、エラーが発生する可能性があります。複数のユーザーが UI を使用してドキュメントを編集する場合、Google ドキュメントではこの処理が透過的に行われます。ただし、API クライアントとしてアプリで管理する必要があります。ドキュメントでの共同作業が予想されない場合でも、防衛的なプログラミングを行い、ドキュメントの状態を一定に保つことが重要です。整合性を確保する方法の 1 つについては、WriteControl セクションをご覧ください。

WriteControl を使用して状態の一貫性を確立する

ドキュメントを読み取って更新する場合、documents.batchUpdate メソッドの WriteControl フィールドを使用して、競合する変更の処理方法の動作を制御できます。WriteControl は、書き込みリクエストの実行方法に対する権限を提供します。

使い方は次のとおりです。

  1. documents.get メソッドを使用してドキュメントを取得し、返された documents リソースから revisionId を保存します。
  2. 更新リクエストを作成します。
  3. オプションの WriteControl オブジェクトを追加し、次の 2 つのオプションのいずれかを指定します。
    1. requiredRevisionId フィールドは、書き込みリクエストが適用されるドキュメントの revisionId に設定されます。API 読み取りリクエスト以降にドキュメントが変更されている場合、書き込みリクエストは処理されず、エラーが返されます。
    2. targetRevisionId フィールドは、書き込みリクエストが適用されるドキュメントの revisionId に設定されます。API 読み取りリクエスト以降にドキュメントが変更された場合、書き込みリクエストの変更は共同編集者の変更に適用されます。書き込みリクエストの結果には、書き込みリクエストの変更と共同編集者によるドキュメントの新しいリビジョンの変更が組み込まれます。ドキュメントサーバーは コンテンツの結合を行います

WriteControl を使用してバッチ リクエストを作成する方法の例については、こちらのバッチ リクエストの例をご覧ください。