Method: documents.batchUpdate

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

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

一部のリクエストには、適用方法に関する情報を提供する replies があります。他のリクエストは情報を返す必要がなく、それぞれ空の返信を返します。返信の順序はリクエストの順序と一致します。

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

他のユーザーがドキュメントを編集している場合があるため、ドキュメントに反映される変更が、ご自身の変更と完全に一致しないことがあります。共同編集者の変更に応じて、ご自身の変更が変更されることがあります。共同編集者がいない場合は、ドキュメントに自分の変更が反映されます。いずれにしても、リクエスト内の更新はアトミックにまとめて適用されることが保証されます。

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 Bad Request エラーが返されます。

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

string

書き込みリクエストが適用されるドキュメントのオプションのターゲット revision ID。

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

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