Method: spreadsheets.values.batchUpdateByDataFilter

在电子表格的一个或多个范围内设置值。调用方必须指定电子表格 ID、valueInputOption,以及一个或多个 DataFilterValueRanges

HTTP 请求

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

网址采用 gRPC 转码语法。

路径参数

参数
spreadsheetId

string

要更新的电子表格的 ID。

请求正文

请求正文中包含结构如下的数据:

JSON 表示法
{
  "valueInputOption": enum (ValueInputOption),
  "data": [
    {
      object (DataFilterValueRange)
    }
  ],
  "includeValuesInResponse": boolean,
  "responseValueRenderOption": enum (ValueRenderOption),
  "responseDateTimeRenderOption": enum (DateTimeRenderOption)
}
字段
valueInputOption

enum (ValueInputOption)

应如何解读输入数据。

data[]

object (DataFilterValueRange)

要应用于电子表格的新值。如果有多个范围与指定的 DataFilter 匹配,则指定的值将应用于所有这些范围。

includeValuesInResponse

boolean

确定更新响应是否应包含已更新的单元格的值。默认情况下,响应不包含更新后的值。每个 BatchUpdateValuesResponse.responses 中的 updatedData 字段包含更新后的值。如果写入的范围大于实际写入的范围,则响应会包含所请求的范围内的所有值(尾随空行和列除外)。

responseValueRenderOption

enum (ValueRenderOption)

确定应如何呈现响应中的值。默认呈现选项为 FORMATTED_VALUE

responseDateTimeRenderOption

enum (DateTimeRenderOption)

确定应如何呈现响应中的日期、时间和时长。如果 responseValueRenderOptionFORMATTED_VALUE,系统会忽略此参数。默认的 dateTime 呈现选项是 SERIAL_NUMBER

响应正文

更新电子表格中一系列值时的响应。

如果成功,响应正文将包含结构如下的数据:

JSON 表示法
{
  "spreadsheetId": string,
  "totalUpdatedRows": integer,
  "totalUpdatedColumns": integer,
  "totalUpdatedCells": integer,
  "totalUpdatedSheets": integer,
  "responses": [
    {
      object (UpdateValuesByDataFilterResponse)
    }
  ]
}
字段
spreadsheetId

string

应用更新的电子表格。

totalUpdatedRows

integer

行中至少包含一个单元格的行总数。

totalUpdatedColumns

integer

列中至少包含一个单元格已更新的列总数。

totalUpdatedCells

integer

已更新的单元格总数。

totalUpdatedSheets

integer

已更新工作表中至少一个单元格的总数。

responses[]

object (UpdateValuesByDataFilterResponse)

每个范围的响应已更新。

授权范围

需要以下 OAuth 范围之一:

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

如需了解详情,请参阅授权指南

数据过滤器值范围

DataFilter 指定位置的值范围。

JSON 表示法
{
  "dataFilter": {
    object (DataFilter)
  },
  "majorDimension": enum (Dimension),
  "values": [
    array
  ]
}
字段
dataFilter

object (DataFilter)

用于描述电子表格中值的位置的数据过滤器。

majorDimension

enum (Dimension)

值的主要维度。

values[]

array (ListValue format)

要写入的数据。如果提供的值超出数据过滤器匹配的任何范围,则请求将失败。如果提供的值小于匹配范围,则仅写入指定值,匹配范围中的现有值不受影响。

UpdateValuesByDataFilterResponse

使用电子表格中的数据过滤器更新一系列值时的响应。

JSON 表示法
{
  "updatedRange": string,
  "updatedRows": integer,
  "updatedColumns": integer,
  "updatedCells": integer,
  "dataFilter": {
    object (DataFilter)
  },
  "updatedData": {
    object (ValueRange)
  }
}
字段
updatedRange

string

应用更新的范围(采用 A1 表示法)。

updatedRows

integer

行中至少包含一个单元格的行数。

updatedColumns

integer

列中至少有一个单元格已更新的列数。

updatedCells

integer

已更新单元格数量。

dataFilter

object (DataFilter)

已选择更新后的范围的数据过滤器。

updatedData

object (ValueRange)

应用所有更新后,dataFilter 所匹配的范围内的单元格值。只有当请求的 includeValuesInResponse 字段为 true 时,才包含此字段。