Add Spreadsheet#append using the dedicated Google Drive API

lib/google_drive/spreadsheet.rb

@@ -131,5 +131,37 @@ def batch_update(requests)
         @session.sheets_service.batch_update_spreadsheet(id, batch_request)
       batch_response.replies
     end
+
+    # Append values to a spreadsheet by first searching for a data table at a range,
+    # then appending the specified values at the end of this data table.
+    #
+    # +range+ The A1 notation of a range to search for a logical table of data. 
+    # Values will be appended after the last row of the table.
+    # +values+ Array (rows) of Array (columns) of values to append to the spreadsheet.
+    # +override_params+ allows you to control how the values will be inserted.
+    #   By default, the values will be interpreted as if typed by a user, 
+    #   and will add new rows instead of ovewriting existing ones.
+    #   So default value is `{ value_input_option: 'USER_ENTERED', insert_data_option: 'INSERT_ROWS' }`
+    #   See https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/append#query-parameters for more information
+    #
+    # Returns an object +UpdateValuesResponse+ that documents the modifications done 
+    # to your spreadsheet.
+    #   
+    # You can read the Google documentation for more information:
+    #   https://developers.google.com/sheets/api/reference/rest/v4/spreadsheets.values/append
+    #
+    # Example: 
+    #   sheet.append_values "A1", [ [ 10, 11, 12 ], [ 20, 21, 22 ] ]
+    # 
+    def append_values(range_name, values, override_params = {})
+      value_range = Google::Apis::SheetsV4::ValueRange.new(values: values)
+      default_params = {
+        value_input_option: 'USER_ENTERED',
+        insert_data_option: 'INSERT_ROWS',
+      }
+      request_body = default_params.merge(override_params)
+      result = @session.sheets_service.append_spreadsheet_value(id, range_name, value_range, request_body)
+      result.updates
+    end
   end
 end

test/test_google_drive.rb

@@ -17,6 +17,52 @@ class TestGoogleDrive < Test::Unit::TestCase
 
   @@session = nil
 
+  def test_spreadsheet_append_values
+    session = get_session
+
+    ss_title = "#{PREFIX}spreadsheet-append-values"
+    ss_copy_title = "#{PREFIX}spreadsheet-append-values-copy"    
+
+    # Removes test spreadsheets in the previous run in case the previous run
+    # failed.
+    for ss in session.files('title' => ss_title, 'title-exact' => 'true')
+      delete_test_file(ss, true)
+    end
+    for ss in session.files('title' => ss_copy_title, 'title-exact' => 'true')
+      delete_test_file(ss, true)
+    end
+
+    ss = session.create_spreadsheet(ss_title)
+    assert { ss.title == ss_title }
+    ws = ss.worksheets[0]
+
+    ss.append_values('A1', [ %w[abc def ghi], %w[jkl mno pqr] ])
+    ws.reload
+    assert { ws.max_rows == 1002 }
+    assert { ws.max_cols == 26 }
+    assert { ws.num_rows == 2 }
+    assert { ws.num_cols == 3 }
+    assert { ws[1, 1] == 'abc' }
+    assert { ws[1, 2] == 'def' }
+    assert { ws[1, 3] == 'ghi' }
+    assert { ws[2, 1] == 'jkl' }
+    assert { ws[2, 2] == 'mno' }
+    assert { ws[2, 3] == 'pqr' }
+
+    ss.append_values("A1", [ %w[stu vwx yz], %w[123 456 789] ])
+    ws.reload
+    assert { ws.max_rows == 1004 }
+    assert { ws.max_cols == 26 }
+    assert { ws.num_rows == 4 }
+    assert { ws.num_cols == 3 }
+    assert { ws[3, 1] == 'stu' }
+    assert { ws[3, 2] == 'vwx' }
+    assert { ws[3, 3] == 'yz' }
+    assert { ws[4, 1] == '123' }
+    assert { ws[4, 2] == '456' }
+    assert { ws[4, 3] == '789' }
+  end
+
   def test_spreadsheet_online
     session = get_session