Method: documents.batchUpdate

ドキュメントに 1 つ以上の更新を適用します。

各 request は適用前に検証されます。いずれかのリクエストが有効でない場合、リクエスト全体が失敗し、何も適用されません。

一部のリクエストでは、どのように適用されているかを示す replies が指定されています。その他のリクエストで情報を返す必要はありません。それぞれ空の応答が返されます。返信の順序はリクエストの順序と同じです。

たとえば、4 つの更新を指定して batchUpdate を呼び出し、3 番目の更新のみが情報を返すとします。レスポンスには、3 番目のリクエストに対する返信と別の空の返信がこの順序で 2 つ含まれています。

他のユーザーがドキュメントを編集している可能性があるため、変更内容がドキュメントに正確に反映されないことがあります。共同編集者による変更に伴って、変更内容も変更されることがあります。共同編集者がいない場合は、変更内容がドキュメントに反映されます。いずれにしても、リクエスト内の更新はアトミックに同時に適用されます。

HTTP リクエスト

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

この URL は gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
documentId

string

更新するドキュメントの ID。

リクエスト本文

リクエストの本文には、次の構造のデータが含まれます。

JSON 表現 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
フィールド
requests[]

object (Request)

ドキュメントに適用する更新のリスト。
writeControl

object (WriteControl)

書き込みリクエストの実行方法を制御します。

レスポンスの本文

documents.batchUpdate リクエストに対するレスポンス メッセージ。

成功した場合、レスポンスの本文には次の構造のデータが含まれます。

JSON 表現 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
フィールド
documentId

string

更新が適用されたドキュメントの ID。
replies[]

object (Response)

更新の返信。これは更新と 1 対 1 で対応付けられていますが、リクエストに対する応答が空である場合もあります。
writeControl

object (WriteControl)

リクエストの適用後に更新された書き込みコントロール。

認可スコープ

次の OAuth スコープのいずれかが必要です。

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

詳細については、承認ガイドをご覧ください。

WriteControl

書き込みリクエストの実行方法を制御します。

JSON 表現 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
フィールド
共用体フィールド control。書き込み先となるドキュメントのリビジョンと、そのリビジョンがドキュメントの現在のリビジョンでない場合のリクエストの動作を指定します。どちらのフィールドも指定されていない場合、更新は最新のリビジョンに適用されます。control は次のいずれかになります。
requiredRevisionId

string

書き込みリクエストが適用されるドキュメントの revision ID（省略可）。ドキュメントの最新のリビジョンでない場合、リクエストは処理されず、400 不正なリクエスト エラーが返されます。

レスポンスで必要なリビジョン ID が返される場合は、リクエストが適用された後のドキュメントのリビジョン ID を示します。
targetRevisionId

string

書き込みリクエストが適用されるドキュメントのターゲット revision ID（省略可）。

API を使用してドキュメントが読み取られた後に共同編集者の変更が発生した場合、この書き込みリクエストによって生成された変更が共同編集者の変更に適用されます。その結果、ドキュメントの新しいリビジョンが作成され、共同編集者による変更とリクエストの変更の両方が組み込まれ、ドキュメント サーバーで競合する変更が解決されます。ターゲット リビジョン ID を使用する場合、API クライアントはドキュメントの別の共同編集者と考えることができます。

ターゲット リビジョン ID は、ドキュメントの最近の版に書き込む場合にのみ使用できます。ターゲット リビジョンが最新のリビジョンから大きく遅れている場合、リクエストは処理されず、400 不正なリクエスト エラーが返されます。ドキュメントの最新バージョンを取得してから、リクエストを再試行する必要があります。通常、リビジョン ID は読み取られてから数分間、ターゲット リビジョンとして有効なままになりますが、頻繁に編集されるドキュメントの場合は、この期間が短くなる可能性があります。