Google Docs API を使用する際は、いくつかの原則に従う必要があります。たとえば、次のようなものが挙げられます。
- 効率的に逆方向に編集する
- コラボレーションを計画する
WriteControlフィールドを使用して状態の整合性を確保する- タブを考慮する
以降のセクションでは、これらの原則について説明します。
効率的に逆方向に編集する
documents.batchUpdate メソッドの 1 回の呼び出し内で、インデックスの場所の降順でリクエストを並べ替えます。これにより、挿入と削除によるインデックスの変更を計算する必要がなくなります。
コラボレーションを計画する
ドキュメントの状態が変化することを想定します。次の図に示すように、あるメソッド呼び出しと別のメソッド呼び出しの間に、他の共同編集者がドキュメントを更新する可能性があります。
インデックスが間違っていると、エラーが発生する可能性があります。複数のユーザーが UI を使用してドキュメントを編集する場合、Google ドキュメントがこの処理を透過的に行います。ただし、API クライアントとして、アプリでこれを管理する必要があります。ドキュメントの共同編集を想定していない場合でも、防御的にプログラミングし、ドキュメントの状態が一貫性を保つようにすることが重要です。一貫性を確保する方法の 1 つについては、WriteControl セクションをご覧ください。
WriteControl で状態の一貫性を確立する
ドキュメントを読み取ってから更新する場合、documents.batchUpdate メソッドの WriteControl フィールドを使用して、競合する変更の処理方法を制御できます。WriteControl は、書き込みリクエストの実行方法に対する権限を提供します。
使用方法は次のとおりです。
documents.getメソッドを使用してドキュメントを取得し、返されたdocumentsリソースからrevisionIdを保存します。- 更新リクエストを作成します。
- 次の 2 つのオプションのいずれかを含む、省略可能な
WriteControlオブジェクトを含めます。requiredRevisionIdフィールドは、書き込みリクエストが適用されるドキュメントのrevisionIdに設定されます。API 読み取りリクエスト以降にドキュメントが変更された場合、書き込みリクエストは処理されず、エラーが返されます。targetRevisionIdフィールドは、書き込みリクエストが適用されるドキュメントのrevisionIdに設定されます。API 読み取りリクエスト以降にドキュメントが変更された場合、書き込みリクエストの変更は共同編集者の変更に対して適用されます。書き込みリクエストの結果には、書き込みリクエストの変更と共同編集者の変更の両方が組み込まれ、ドキュメントの新しいリビジョンが作成されます。コンテンツの統合は Docs サーバーが行います。
WriteControl を使用してバッチ リクエストを作成する方法の例については、バッチ リクエストの例をご覧ください。
タブを考慮する
1 つのドキュメントに複数のタブを含めることができます。この場合、API リクエストで特別な処理が必要になります。
次の点にご留意ください。
documents.getメソッドでincludeTabsContentパラメータをtrueに設定して、ドキュメント内のすべてのタブからコンテンツを取得します。デフォルトでは、すべてのタブのコンテンツが返されるわけではありません。documents.batchUpdateメソッドで、各Requestを適用するタブの ID を指定します。各Requestには、更新を適用するタブを指定する方法が含まれています。デフォルトでは、タブが指定されていない場合、ほとんどの場合、Requestはドキュメントの最初のタブに適用されます。詳しくは、Requestのドキュメントをご覧ください。