Method: spreadsheets.batchUpdate

Applies one or more updates to the spreadsheet.

Each request is validated before being applied. If any request is not valid then the entire request will fail and nothing will be applied.

Some requests have replies to give you some information about how they are applied. The replies will mirror the requests. For example, if you applied 4 updates and the 3rd one had a reply, then the response will have 2 empty replies, the actual reply, and another empty reply, in that order.

Due to the collaborative nature of spreadsheets, it is not guaranteed that the spreadsheet will reflect exactly your changes after this completes, however it is guaranteed that the updates in the request will be applied together atomically. Your changes may be altered with respect to collaborator changes. If there are no collaborators, the spreadsheet should reflect your changes.

HTTP request

POST https://sheets.googleapis.com/v4/spreadsheets/{spreadsheetId}:batchUpdate

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
spreadsheetId

string

The spreadsheet to apply the updates to.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "includeSpreadsheetInResponse": boolean,
  "responseRanges": [
    string
  ],
  "responseIncludeGridData": boolean,
  "commentsViewMode": enum (CommentsViewMode)
}
Fields
requests[]

object (Request)

A list of updates to apply to the spreadsheet. Requests will be applied in the order they are specified. If any request is not valid, no requests will be applied.
includeSpreadsheetInResponse

boolean

Determines if the update response should include the spreadsheet resource.
responseRanges[]

string

Limits the ranges included in the response spreadsheet. Meaningful only if includeSpreadsheetInResponse is 'true'.
responseIncludeGridData

boolean

True if grid data should be returned. Meaningful only if includeSpreadsheetInResponse is 'true'. This parameter is ignored if a field mask was set in the request.
commentsViewMode

enum (CommentsViewMode)

The comments view mode to apply to the spreadsheet. This allows viewing the spreadsheet with comments omitted or included. If one is not specified, COMMENTS_VIEW_MODE_OMITTED is used. Meaningful only if includeSpreadsheetInResponse is 'true'.

Response body

The reply for batch updating a spreadsheet.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "spreadsheetId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "updatedSpreadsheet": {
    object (Spreadsheet)
  },
  "commentUpdateState": enum (CommentUpdateState)
}
Fields
spreadsheetId

string

The spreadsheet the updates were applied to.
replies[]

object (Response)

The reply of the updates. This maps 1:1 with the updates, although replies to some requests may be empty.
updatedSpreadsheet

object (Spreadsheet)

The spreadsheet after updates were applied. This is only set if BatchUpdateSpreadsheetRequest.include_spreadsheet_in_response is true.
commentUpdateState

enum (CommentUpdateState)

Whether comment updates were applied in the batch request.

Authorization scopes

Requires one of the following OAuth scopes:

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

For more information, see the Authorization guide.

CommentUpdateState

The status of comment updates in the batch request.

Enums
COMMENT_UPDATE_STATE_UNSPECIFIED The status of comment updates is unspecified.
NO_UPDATES_REQUESTED No comment updates were requested in the batch request.
ALL_SAVED All requested comment updates were applied in the batch request.
ALL_FAILED_UNKNOWN_REASON All requested comment updates failed.