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

Google Docs API を使用する際は、いくつかの原則に従う必要があります。 以下はその一例です。

  • 効率を高めるために逆方向に編集する
  • 共同作業を計画する
  • ` WriteControl ` フィールドを使用して状態の一貫性を確保する
  • タブを考慮する

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

効率を高めるために逆方向に編集する

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

共同作業を計画する

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

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

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

WriteControl で状態の一貫性を確立する

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

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

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

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

タブを考慮する

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

注意点:

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