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 は読み取り後数分間、ターゲット リビジョンとして使用できますが、頻繁に編集されるドキュメントの場合は、この期間が短くなることがあります。