append method

Future<AppendValuesResponse> append(ValueRange request, String spreadsheetId, String range, { bool? includeValuesInResponse, String? insertDataOption, String? responseDateTimeRenderOption, String? responseValueRenderOption, String? valueInputOption, String? $fields, })

Appends values to a spreadsheet.

The input range is used to search for existing data and find a "table" within that range. Values will be appended to the next row of the table, starting with the first column of the table. See the [guide](/sheets/api/guides/values#appending_values) and [sample code](/sheets/api/samples/writing#append_values) for specific details of how tables are detected and data is appended. The caller must specify the spreadsheet ID, range, and a valueInputOption. The valueInputOption only controls how the input data will be added to the sheet (column-wise or row-wise), it does not influence what cell the data starts being written to.

request - The metadata request object.

Request parameters:

spreadsheetId - The ID of the spreadsheet to update.

range - The [A1 notation](/sheets/api/guides/concepts#cell) of a range to search for a logical table of data. Values are appended after the last row of the table.

includeValuesInResponse - Determines if the update response should include the values of the cells that were appended. By default, responses do not include the updated values.

insertDataOption - How the input data should be inserted. Possible string values are:

• "OVERWRITE" : The new data overwrites existing data in the areas it is written. (Note: adding data to the end of the sheet will still insert new rows or columns so the data can be written.)
• "INSERT_ROWS" : Rows are inserted for the new data.

responseDateTimeRenderOption - Determines how dates, times, and durations in the response should be rendered. This is ignored if response_value_render_option is FORMATTED_VALUE. The default dateTime render option is SERIAL_NUMBER. Possible string values are:

• "SERIAL_NUMBER" : Instructs date, time, datetime, and duration fields to be output as doubles in "serial number" format, as popularized by Lotus 1-2-3. The whole number portion of the value (left of the decimal) counts the days since December 30th 1899. The fractional portion (right of the decimal) counts the time as a fraction of the day. For example, January 1st 1900 at noon would be 2.5, 2 because it's 2 days after December 30th 1899, and .5 because noon is half a day. February 1st 1900 at 3pm would be 33.625. This correctly treats the year 1900 as not a leap year.
• "FORMATTED_STRING" : Instructs date, time, datetime, and duration fields to be output as strings in their given number format (which depends on the spreadsheet locale).

responseValueRenderOption - Determines how values in the response should be rendered. The default render option is FORMATTED_VALUE. Possible string values are:

• "FORMATTED_VALUE" : Values will be calculated & formatted in the response according to the cell's formatting. Formatting is based on the spreadsheet's locale, not the requesting user's locale. For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would return "$1.23".
• "UNFORMATTED_VALUE" : Values will be calculated, but not formatted in the reply. For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would return the number 1.23.
• "FORMULA" : Values will not be calculated. The reply will include the formulas. For example, if A1 is 1.23 and A2 is =A1 and formatted as currency, then A2 would return "=A1". Sheets treats date and time values as decimal values. This lets you perform arithmetic on them in formulas. For more information on interpreting date and time values, see [About date & time values](https://developers.google.com/sheets/api/guides/formats#about_date_time_values).

valueInputOption - How the input data should be interpreted. Possible string values are:

• "INPUT_VALUE_OPTION_UNSPECIFIED" : Default input value. This value must not be used.
• "RAW" : The values the user has entered will not be parsed and will be stored as-is.
• "USER_ENTERED" : The values will be parsed as if the user typed them into the UI. Numbers will stay as numbers, but strings may be converted to numbers, dates, etc. following the same rules that are applied when entering text into a cell via the Google Sheets UI.

$fields - Selector specifying which fields to include in a partial response.

Completes with a AppendValuesResponse.

Completes with a commons.ApiRequestError if the API endpoint returned an error.

If the used http.Client completes with an error when making a REST call, this method will complete with the same error.

Implementation

async.Future<AppendValuesResponse> append(
  ValueRange request,
  core.String spreadsheetId,
  core.String range, {
  core.bool? includeValuesInResponse,
  core.String? insertDataOption,
  core.String? responseDateTimeRenderOption,
  core.String? responseValueRenderOption,
  core.String? valueInputOption,
  core.String? $fields,
}) async {
  final body_ = convert.json.encode(request);
  final queryParams_ = <core.String, core.List<core.String>>{
    if (includeValuesInResponse != null)
      'includeValuesInResponse': ['${includeValuesInResponse}'],
    if (insertDataOption != null) 'insertDataOption': [insertDataOption],
    if (responseDateTimeRenderOption != null)
      'responseDateTimeRenderOption': [responseDateTimeRenderOption],
    if (responseValueRenderOption != null)
      'responseValueRenderOption': [responseValueRenderOption],
    if (valueInputOption != null) 'valueInputOption': [valueInputOption],
    if ($fields != null) 'fields': [$fields],
  };

  final url_ = 'v4/spreadsheets/' +
      commons.escapeVariable('$spreadsheetId') +
      '/values/' +
      commons.escapeVariable('$range') +
      ':append';

  final response_ = await _requester.request(
    url_,
    'POST',
    body: body_,
    queryParams: queryParams_,
  );
  return AppendValuesResponse.fromJson(
      response_ as core.Map<core.String, core.dynamic>);
}