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 読み取りリクエスト以降にドキュメントが変更された場合、書き込みリクエストの変更は、コラボレーターの変更に適用されます。書き込みリクエストの結果には、書き込みリクエストの変更と共同編集者の変更の両方がドキュメントの新しいリビジョンに反映されます。ドキュメントサーバーはコンテンツを マージする役割を担います
WriteControl
を使用してバッチ リクエストを作成する方法の例については、こちらのバッチ リクエストの例をご覧ください。