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

Google Docs API を使用する際には、いくつかの原則に従う必要があります。次のようなアクセサリーが含まれます。

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

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

効率的に編集する

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

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

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

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

WriteControl を使用して状態の整合性を確立する

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

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

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

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

タブを考慮する

1 つのドキュメントに複数のタブを含めることができ、各タブでは API リクエストで特定の処理を行う必要があります。

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

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

関連トピック

• バッチ リクエスト
• リクエストとレスポンス
• タブの操作