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

Google Docs API を使用する際は、いくつかの原則に従う必要があります。たとえば、次のような疑問があります。

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

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

効率的に逆方向に編集する

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

コラボレーションを計画する

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

メソッド呼び出し間でドキュメントがどのように変化するか。

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

WriteControl で状態の整合性を確立する

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

使用方法は次のとおりです。

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

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

タブを考慮する

1 つのドキュメントに複数のタブを含めることができます。この場合、API リクエストで特別な処理が必要になります。

次の点にご留意ください。

  1. documents.get メソッドで includeTabsContent パラメータを true に設定して、ドキュメント内のすべてのタブからコンテンツを取得します。デフォルトでは、すべてのタブのコンテンツが返されるわけではありません。
  2. documents.batchUpdate メソッドで、各 Request を適用するタブの ID を指定します。各 Request には、更新を適用するタブを指定する方法が含まれています。デフォルトでは、タブが指定されていない場合、ほとんどの場合、Request はドキュメントの最初のタブに適用されます。詳しくは、Request のドキュメントをご覧ください。