קריאה וכתיבה של ערכי תאים

במאמר הזה נסביר את העקרונות הבסיסיים של השימוש במשאב spreadsheets.values.

בגיליונות אלקטרוניים יכולים להיות כמה גיליונות, ובכל גיליון יכולים להיות מספר שורות או עמודות. תא הוא מיקום בצומת של שורה ועמודה מסוימות, והוא יכול להכיל ערך נתונים. ‫Google Sheets API מספק את המשאב spreadsheets.values כדי לאפשר קריאה וכתיבה של ערכים.

אם אתם צריכים להוסיף שורות או לעדכן את העיצוב ומאפיינים אחרים בגיליון, אתם צריכים להשתמש בשיטה batchUpdate של מקור המידע spreadsheets, כמו שמתואר במאמר עדכון גיליונות אלקטרוניים.

שיטות של משאבים

במשאב spreadsheets.values יש את השיטות הבאות לקריאה ולכתיבה של ערכים, כל אחת למשימה ספציפית:

גישה לטווח	קריאה	כתיבה
טווח יחיד	spreadsheets.values.get	spreadsheets.values.update
כמה טווחים	spreadsheets.values.batchGet	spreadsheets.values.batchUpdate
הוספה		spreadsheets.values.append

באופן כללי, מומלץ לשלב כמה קריאות או עדכונים באמצעות השיטות batchGet ו-batchUpdate (בהתאמה), כי זה משפר את היעילות.

דוגמאות קוד לכל אחת מהשיטות האלה מופיעות בדפים דוגמאות בסיסיות לקריאה ודוגמאות בסיסיות לכתיבה. כדי לראות את כל דוגמאות הקוד, אפשר לעיין בדף הסקירה הכללית של הדוגמאות.

קריאת ערכי תאים

כדי לקרוא ערכי נתונים מגיליון, צריך את מזהה הגיליון האלקטרוני ואת סימון A1 לטווח. אם מציינים את הטווח בלי מזהה הגיליון (A1:B2), הבקשה מופעלת בגיליון הראשון בגיליון האלקטרוני. מידע נוסף על מזהי גיליונות אלקטרוניים ועל סימון A1 זמין בסקירה הכללית של Google Sheets API.

יש כמה פרמטרים אופציונליים של שאילתה ששולטים בפורמט של הפלט:

פרמטר של עיצוב	ערך ברירת המחדל
majorDimension	ROWS
valueRenderOption	FORMATTED_VALUE
dateTimeRenderOption	SERIAL_NUMBER

חשוב לזכור: אתם צריכים להשתמש ב-dateTimeRenderOption רק אם valueRenderOption לא FORMATTED_VALUE.

אין הגבלה מפורשת על כמות הנתונים שמוחזרת. אם יש שגיאות, לא מוחזרים נתונים. שורות ועמודות ריקות בסוף הטבלה לא נכללות.

בקטעים הבאים מתוארות השיטות singular ו-batch get. דוגמאות נוספות לקוד של פעולות קריאה בסיסיות מופיעות במאמר קריאה בסיסית.

קריאת ערכים מטווח יחיד

כדי לקרוא טווח יחיד של ערכים מגיליון אלקטרוני, משתמשים בבקשה spreadsheets.values.get:

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-GitHub

/**
 * Gets the values of the cells in the specified range
 * @param {string} spreadsheetId id of the spreadsheet
 * @param {string} range specifying the start and end cells of the range
 * @returns {*} Values in the range
 */
Snippets.prototype.getValues = (spreadsheetId, range) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.getActiveSpreadsheet()
  //     .getRange(range).getValues(values) is more appropriate.
  try {
    const result = Sheets.Spreadsheets.Values.get(spreadsheetId, range);
    const numRows = result.values ? result.values.length : 0;
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/GetValues.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.ValueRange;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;

/* Class to demonstrate the use of Spreadsheet Get Values API */
public class GetValues {
  /**
   * Returns a range of values from a spreadsheet.
   *
   * @param spreadsheetId - Id of the spreadsheet.
   * @param range         - Range of cells of the spreadsheet.
   * @return Values in the range
   * @throws IOException - if credentials file not found.
   */
  public static ValueRange getValues(String spreadsheetId, String range) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    ValueRange result = null;
    try {
      // Gets the values of the cells in the specified range.
      result = service.spreadsheets().values().get(spreadsheetId, range).execute();
      int numRows = result.getValues() != null ? result.getValues().size() : 0;
      System.out.printf("%d rows retrieved.", numRows);
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return result;
  }
}

JavaScript

sheets/snippets/sheets_get_values.js

הצגת הקוד ב-GitHub

function getValues(spreadsheetId, range, callback) {
  try {
    gapi.client.sheets.spreadsheets.values.get({
      spreadsheetId: spreadsheetId,
      range: range,
    }).then((response) => {
      const result = response.result;
      const numRows = result.values ? result.values.length : 0;
      console.log(`${numRows} rows retrieved.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_get_values.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Gets cell values from a spreadsheet.
 * @param {string} spreadsheetId The ID of the spreadsheet.
 * @param {string} range The range of cells to retrieve.
 * @return {Promise<object>} The response from the get request.
 */
async function getValues(spreadsheetId, range) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});
  // Get the values from the specified range.
  const result = await service.spreadsheets.values.get({
    spreadsheetId,
    range,
  });
  const numRows = result.data.values ? result.data.values.length : 0;
  console.log(`${numRows} rows retrieved.`);
  return result;
}

PHP

sheets/snippets/src/SpreadsheetGetValues.php

הצגת הקוד ב-GitHub

<?php
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets\BatchUpdateSpreadsheetRequest;
/**
 * get values of a particular spreadsheet(by Id and range).
 */
function getValues($spreadsheetId, $range)
    {   
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        $result = $service->spreadsheets_values->get($spreadsheetId, $range);
        try{
        $numRows = $result->getValues() != null ? count($result->getValues()) : 0;
        printf("%d rows retrieved.", $numRows);
        return $result;
    }
        catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
        }
    }

Python

sheets/snippets/sheets_get_values.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def get_values(spreadsheet_id, range_name):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    result = (
        service.spreadsheets()
        .values()
        .get(spreadsheetId=spreadsheet_id, range=range_name)
        .execute()
    )
    rows = result.get("values", [])
    print(f"{len(rows)} rows retrieved")
    return result
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: spreadsheet_id, and range_name
  get_values("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k", "A1:C2")

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

הצגת הקוד ב-GitHub

result = service.get_spreadsheet_values(spreadsheet_id, range_name)
num_rows = result.values ? result.values.length : 0
puts "#{num_rows} rows received."

התשובה לבקשה הזו מוחזרת כאובייקט ValueRange שהוא חלק מהמשאב spreadsheets.values.

קריאת ערכים מכמה טווחים

כדי לקרוא כמה טווחים של ערכים לא רציפים מגיליון אלקטרוני, משתמשים בבקשת spreadsheets.values.batchGet שמאפשרת לציין כמה טווחים לאחזור:

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-GitHub

/**
 * Get the values in the specified ranges
 * @param {string} spreadsheetId spreadsheet's ID
 * @param {list<string>} _ranges The span of ranges
 * @returns {*} spreadsheet information and values
 */
Snippets.prototype.batchGetValues = (spreadsheetId, _ranges) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.getActiveSpreadsheet()
  //     .getRange(range).getValues(values) is more appropriate.
  let ranges = [
    //Range names ...
  ];
  try {
    const result = Sheets.Spreadsheets.Values.batchGet(spreadsheetId, {
      ranges: ranges,
    });
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/BatchGetValues.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.BatchGetValuesResponse;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;
import java.util.List;

/* Class to demonstrate the use of Spreadsheet Batch Get Values API */
public class BatchGetValues {
  /**
   * Returns one or more ranges of values from a spreadsheet.
   *
   * @param spreadsheetId - Id of the spreadsheet.
   * @param ranges        - Range of cells of the spreadsheet.
   * @return Values in the range
   * @throws IOException - if credentials file not found.
   */
  public static BatchGetValuesResponse batchGetValues(String spreadsheetId,
                                                      List<String> ranges)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    BatchGetValuesResponse result = null;
    try {
      // Gets the values of the cells in the specified range.
      result = service.spreadsheets().values().batchGet(spreadsheetId)
          .setRanges(ranges).execute();
      System.out.printf("%d ranges retrieved.", result.getValueRanges().size());
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return result;
  }
}

JavaScript

sheets/snippets/sheets_batch_get_values.js

הצגת הקוד ב-GitHub

function batchGetValues(spreadsheetId, _ranges, callback) {
  let ranges = [
    // Range names ...
  ];
  ranges = _ranges;
  try {
    gapi.client.sheets.spreadsheets.values.batchGet({
      spreadsheetId: spreadsheetId,
      ranges: ranges,
    }).then((response) => {
      const result = response.result;
      console.log(`${result.valueRanges.length} ranges retrieved.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_batch_get_values.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Batch gets cell values from a spreadsheet.
 * @param {string} spreadsheetId The ID of the spreadsheet.
 * @param {string} _ranges The ranges of cells to retrieve.
 * @return {obj} The spreadsheet information.
 */
async function batchGetValues(spreadsheetId, _ranges) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The ranges to retrieve from the spreadsheet.
  let ranges = [
    // e.g., 'Sheet1!A1:C5',
    // 'Sheet2!A1:B3'
  ];

PHP

sheets/snippets/src/SpreadsheetBatchGetValues.php

הצגת הקוד ב-GitHub

<?php

use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets;
/**
 * method to get a spreadsheet values in batch
 */

function batchGetValues($spreadsheetId)
    {
        /* Load pre-authorized user credentials from the environment.
        TODO(developer) - See https://developers.google.com/identity for
        guides on implementing OAuth2 for your application. */       
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        try{
            $ranges = 'Sheet1!A1:B2';
            $params = array(
                'ranges' => $ranges
            );
            //execute the request
            $result = $service->spreadsheets_values->batchGet($spreadsheetId, $params);
            printf("%d ranges retrieved.", count($result->getValueRanges()));
            return $result;
        }
        catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
          }
        }

Python

sheets/snippets/sheets_batch_get_values.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def batch_get_values(spreadsheet_id, _range_names):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)
    range_names = [
        # Range names ...
    ]
    result = (
        service.spreadsheets()
        .values()
        .batchGet(spreadsheetId=spreadsheet_id, ranges=range_names)
        .execute()
    )
    ranges = result.get("valueRanges", [])
    print(f"{len(ranges)} ranges retrieved")
    return result
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: spreadsheet_id, and range_name

  batch_get_values("1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k", "A1:C2")

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

הצגת הקוד ב-GitHub

range_names = [
  # Range names ...
]
result = service.batch_get_spreadsheet_values(spreadsheet_id,
                                              ranges: range_names)
puts "#{result.value_ranges.length} ranges retrieved."

התשובה לבקשה הזו מוחזרת כאובייקט BatchGetValuesResponse שמכיל את spreadsheetId ורשימה של אובייקטים מסוג ValueRange.

כתיבה של ערכי תאים

כדי לכתוב לגיליון, צריך את מזהה הגיליון האלקטרוני, את טווח התאים בסימון A1 ואת הנתונים שרוצים לכתוב באובייקט מתאים של גוף הבקשה. מידע נוסף על מזהי גיליונות אלקטרוניים ועל סימון A1 זמין במאמר סקירה כללית על Google Sheets API.

יש כמה פרמטרים של שאילתות שקובעים איך הנתונים נכתבים ואיך התגובה מעוצבת:

כתיבת פרמטר	ערך ברירת המחדל
valueInputOption	(חובה)
includeValuesInResponse	false
responseValueRenderOption	FORMATTED_VALUE
responseDateTimeRenderOption	SERIAL_NUMBER

הפרמטר הנדרש valueInputOption קובע איך צריך לפרש את נתוני הקלט. (בעדכונים בכמות גדולה, הפרמטר הזה מצוין בגוף הבקשה). האפשרויות הנתמכות מתוארות בטבלה הבאה:

ValueInputOption	תיאור
RAW	הקלט לא מנותח ומוסיפים אותו כמחרוזת. לדוגמה, אם מזינים את הקלט ‎=1+2, המחרוזת ‎=1+2 מוצבת בתא, ולא הנוסחה. (ערכים שאינם מחרוזות, כמו ערכים בוליאניים או מספרים, תמיד מטופלים כ-RAW).
USER_ENTERED	הקלט מנותח בדיוק כמו שהוא מוזן לממשק המשתמש של Sheets. לדוגמה, המחרוזת 'Mar 1 2016' הופכת לתאריך, והמחרוזת '‎=1+2' הופכת לנוסחה. אפשר גם להסיק את הפורמט, כך שהערך ‎ "$100.15" הופך למספר עם עיצוב של מטבע.

חשוב לזכור: אתם צריכים להשתמש ב-responseDateTimeRenderOption רק אם responseValueRenderOption לא FORMATTED_VALUE.

בקטעים הבאים מתוארות השיטות לעדכון פריט יחיד ולעדכון קבוצת פריטים. דוגמאות נוספות לקוד של פעולות כתיבה בסיסיות מופיעות במאמר בנושא כתיבה בסיסית.

כתיבת ערכים לטווח יחיד

כדי לכתוב נתונים לטווח יחיד, משתמשים בבקשת spreadsheets.values.update:

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-GitHub

/**
 * Updates the values in the specified range
 * @param {string} spreadsheetId spreadsheet's ID
 * @param {string} range the range of cells in spreadsheet
 * @param {string} valueInputOption determines how the input should be interpreted
 * @see
 * https://developers.google.com/sheets/api/reference/rest/v4/ValueInputOption
 * @param {list<list<string>>} _values list of string lists to input
 * @returns {*} spreadsheet with updated values
 */
Snippets.prototype.updateValues = (
  spreadsheetId,
  range,
  valueInputOption,
  _values,
) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.getActiveSpreadsheet()
  //     .getRange(range).setValues(values) is more appropriate.
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];

  try {
    const valueRange = Sheets.newValueRange();
    valueRange.values = values;
    const result = Sheets.Spreadsheets.Values.update(
      valueRange,
      spreadsheetId,
      range,
      { valueInputOption: valueInputOption },
    );
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/UpdateValues.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.UpdateValuesResponse;
import com.google.api.services.sheets.v4.model.ValueRange;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;
import java.util.List;

/* Class to demonstrate the use of Spreadsheet Update Values API */
public class UpdateValues {
  /**
   * Sets values in a range of a spreadsheet.
   *
   * @param spreadsheetId    - Id of the spreadsheet.
   * @param range            - Range of cells of the spreadsheet.
   * @param valueInputOption - Determines how input data should be interpreted.
   * @param values           - List of rows of values to input.
   * @return spreadsheet with updated values
   * @throws IOException - if credentials file not found.
   */
  public static UpdateValuesResponse updateValues(String spreadsheetId,
                                                  String range,
                                                  String valueInputOption,
                                                  List<List<Object>> values)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    UpdateValuesResponse result = null;
    try {
      // Updates the values in the specified range.
      ValueRange body = new ValueRange()
          .setValues(values);
      result = service.spreadsheets().values().update(spreadsheetId, range, body)
          .setValueInputOption(valueInputOption)
          .execute();
      System.out.printf("%d cells updated.", result.getUpdatedCells());
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return result;
  }
}

JavaScript

sheets/snippets/sheets_update_values.js

הצגת הקוד ב-GitHub

function updateValues(spreadsheetId, range, valueInputOption, _values, callback) {
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];
  values = _values;
  const body = {
    values: values,
  };
  try {
    gapi.client.sheets.spreadsheets.values.update({
      spreadsheetId: spreadsheetId,
      range: range,
      valueInputOption: valueInputOption,
      resource: body,
    }).then((response) => {
      const result = response.result;
      console.log(`${result.updatedCells} cells updated.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_update_values.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Updates values in a spreadsheet.
 * @param {string} spreadsheetId The ID of the spreadsheet to update.
 * @param {string} range The range of cells to update.
 * @param {string} valueInputOption How the input data should be interpreted.
 * @param {(string[])[]} _values A 2D array of values to update.
 * @return {Promise<object>} The response from the update request.
 */
async function updateValues(spreadsheetId, range, valueInputOption, _values) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The values to update in the spreadsheet.
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];

  // Create the request body.
  const resource = {
    values,
  };

  // Update the values in the spreadsheet.
  const result = await service.spreadsheets.values.update({
    spreadsheetId,
    range,
    valueInputOption,
    resource,
  });

  // Log the number of updated cells.
  console.log('%d cells updated.', result.data.updatedCells);
  return result;
}

PHP

sheets/snippets/src/SpreadsheetUpdateValues.php

הצגת הקוד ב-GitHub

<?php
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets\ValueRange;


function updateValues($spreadsheetId, $range, $valueInputOption)
    {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        try{
        $values = [["sample", 'values']];

        $body = new Google_Service_Sheets_ValueRange([
            'values' => $values
        ]);
        $params = [
            'valueInputOption' => $valueInputOption
        ];
        //executing the request
        $result = $service->spreadsheets_values->update($spreadsheetId, $range,
        $body, $params);
        printf("%d cells updated.", $result->getUpdatedCells());
        return $result;
    }
    catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
          }
    }

Python

sheets/snippets/sheets_update_values.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def update_values(spreadsheet_id, range_name, value_input_option, _values):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)
    values = [
        [
            # Cell values ...
        ],
        # Additional rows ...
    ]
    body = {"values": values}
    result = (
        service.spreadsheets()
        .values()
        .update(
            spreadsheetId=spreadsheet_id,
            range=range_name,
            valueInputOption=value_input_option,
            body=body,
        )
        .execute()
    )
    print(f"{result.get('updatedCells')} cells updated.")
    return result
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: spreadsheet_id,  range_name, value_input_option and  _values
  update_values(
      "1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k",
      "A1:C2",
      "USER_ENTERED",
      [["A", "B"], ["C", "D"]],
  )

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

הצגת הקוד ב-GitHub

values = [
  [
    # Cell values ...
  ]
  # Additional rows ...
]
data = [
  {
    range:  range_name,
    values: values
  },
  # Additional ranges to update ...
]
value_range_object = Google::Apis::SheetsV4::ValueRange.new(range:  range_name,
                                                            values: values)
result = service.update_spreadsheet_value(spreadsheet_id,
                                          range_name,
                                          value_range_object,
                                          value_input_option: value_input_option)
puts "#{result.updated_cells} cells updated."

גוף בקשת העדכון חייב להיות אובייקט ValueRange, אבל שדה החובה היחיד הוא values. אם מציינים את הערך range, הוא חייב להתאים לטווח בכתובת ה-URL. ב-ValueRange, אפשר לציין את majorDimension. כברירת מחדל, נעשה שימוש ב-ROWS. אם מציינים את COLUMNS, כל מערך פנימי נכתב בעמודה במקום בשורה.

כשמעדכנים, המערכת מדלגת על ערכים ללא נתונים. כדי לנקות נתונים, משתמשים במחרוזת ריקה (""). אפשר גם לנקות ערכים מכמה טווחים בלי להחליף אותם באמצעות השיטה spreadsheets.values.batchClear.

אם אתם משתמשים במטא-נתונים של מפתחים, תוכלו לעיין במדריך למטא-נתונים של מפתחים כדי לקבל מידע על שימוש במסנני נתונים לקריאה, לעדכון או לניקוי של ערכים באמצעות השיטות spreadsheets.values.batchGetByDataFilter,‏ spreadsheets.values.batchUpdateByDataFilter ו-spreadsheets.values.batchClearByDataFilter.

הערה: פרמטר range יכול לציין כמה תאים (לדוגמה, A1:D5) או תא אחד (לדוגמה, A1). אם מצוינים כמה תאים, נתוני הקלט צריכים להיות בטווח הזה. אם מצוין תא בודד, נתוני הקלט מתחילים בקואורדינטה הזו ויכולים להתרחב לכל מספר של שורות או עמודות.

כתיבת ערכים לכמה טווחים

אם רוצים לכתוב כמה טווחים לא רציפים, אפשר להשתמש בבקשה spreadsheets.values.batchUpdate:

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-GitHub

/**
 * Updates the values in the specified range
 * @param {string} spreadsheetId spreadsheet's ID
 * @param {string} range range of cells of the spreadsheet
 * @param {string} valueInputOption determines how the input should be interpreted
 * @see
 * https://developers.google.com/sheets/api/reference/rest/v4/ValueInputOption
 * @param {list<list<string>>} _values list of string values to input
 * @returns {*} spreadsheet with updated values
 */
Snippets.prototype.batchUpdateValues = (
  spreadsheetId,
  range,
  valueInputOption,
  _values,
) => {
  // This code uses the Sheets Advanced Service, but for most use cases
  // the built-in method SpreadsheetApp.getActiveSpreadsheet()
  //     .getRange(range).setValues(values) is more appropriate.
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];

  try {
    const valueRange = Sheets.newValueRange();
    valueRange.range = range;
    valueRange.values = values;

    const batchUpdateRequest = Sheets.newBatchUpdateValuesRequest();
    batchUpdateRequest.data = valueRange;
    batchUpdateRequest.valueInputOption = valueInputOption;

    const result = Sheets.Spreadsheets.Values.batchUpdate(
      batchUpdateRequest,
      spreadsheetId,
    );
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/BatchUpdateValues.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.BatchUpdateValuesRequest;
import com.google.api.services.sheets.v4.model.BatchUpdateValuesResponse;
import com.google.api.services.sheets.v4.model.ValueRange;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

/* Class to demonstrate the use of Spreadsheet Batch Update Values API */
public class BatchUpdateValues {
  /**
   * Set values in one or more ranges of spreadsheet.
   *
   * @param spreadsheetId    - Id of the spreadsheet.
   * @param range            - Range of cells of the spreadsheet.
   * @param valueInputOption - Determines how input data should be interpreted.
   * @param values           - list of rows of values to input.
   * @return spreadsheet with updated values
   * @throws IOException - if credentials file not found.
   */
  public static BatchUpdateValuesResponse batchUpdateValues(String spreadsheetId,
                                                            String range,
                                                            String valueInputOption,
                                                            List<List<Object>> values)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    List<ValueRange> data = new ArrayList<>();
    data.add(new ValueRange()
        .setRange(range)
        .setValues(values));

    BatchUpdateValuesResponse result = null;
    try {
      // Updates the values in the specified range.
      BatchUpdateValuesRequest body = new BatchUpdateValuesRequest()
          .setValueInputOption(valueInputOption)
          .setData(data);
      result = service.spreadsheets().values().batchUpdate(spreadsheetId, body).execute();
      System.out.printf("%d cells updated.", result.getTotalUpdatedCells());
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return result;
  }
}

JavaScript

sheets/snippets/sheets_batch_update_values.js

הצגת הקוד ב-GitHub

function batchUpdateValues(spreadsheetId, range, valueInputOption, _values, callback) {
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];
  values = _values;
  const data = [];
  data.push({
    range: range,
    values: values,
  });
  // Additional ranges to update.

  const body = {
    data: data,
    valueInputOption: valueInputOption,
  };
  try {
    gapi.client.sheets.spreadsheets.values.batchUpdate({
      spreadsheetId: spreadsheetId,
      resource: body,
    }).then((response) => {
      const result = response.result;
      console.log(`${result.totalUpdatedCells} cells updated.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_batch_update_values.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Batch updates values in a spreadsheet.
 * @param {string} spreadsheetId The ID of the spreadsheet to update.
 * @param {string} range The range of cells to update.
 * @param {string} valueInputOption How the input data should be interpreted.
 * @param {(string[])[]} _values A 2D array of values to update.
 * @return {Promise<object>} The response from the batch update.
 */
async function batchUpdateValues(
  spreadsheetId,
  range,
  valueInputOption,
  _values,
) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The values to update in the spreadsheet.
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];

  // The data to be updated.
  const data = [
    {
      range,
      values,
    },
  ];

  // Additional ranges to update can be added here.

  // Create the batch update request.
  const resource = {
    data,
    valueInputOption,
  };

  // Execute the batch update request.
  const result = await service.spreadsheets.values.batchUpdate({
    spreadsheetId,
    resource,
  });

  // Log the number of updated cells.
  console.log('%d cells updated.', result.data.totalUpdatedCells);
  return result;
}

PHP

sheets/snippets/src/SpreadsheetBatchUpdateValues.php

הצגת הקוד ב-GitHub

<?php
/**
 * to update values in batch for a particular spreadsheet
 */
use Google\Client;
use Google\Service\Drive;
use Google\Service\Sheets;

function batchUpdateValues($spreadsheetId, $range, $valueInputOption)
    {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
        $client = new Google\Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Google\Service\Drive::DRIVE);
        $service = new Google_Service_Sheets($client);
        $values = [];
        try{

            $data[] = new Google_Service_Sheets_ValueRange([
                'range' => $range,
            'values' => $values
        ]);
        $body = new Google_Service_Sheets_BatchUpdateValuesRequest([
            'valueInputOption' => $valueInputOption,
            'data' => $data
        ]);
        $result = $service->spreadsheets_values->batchUpdate($spreadsheetId, $body);
        printf("%d cells updated.", $result->getTotalUpdatedCells());
        return $result;
    }

        catch(Exception $e) {
            // TODO(developer) - handle error appropriately
            echo 'Message: ' .$e->getMessage();
          }
    }

Python

sheets/snippets/sheets_batch_update_values.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def batch_update_values(
    spreadsheet_id, range_name, value_input_option, _values
):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    values = [
        [
            # Cell values ...
        ],
        # Additional rows
    ]
    data = [
        {"range": range_name, "values": values},
        # Additional ranges to update ...
    ]
    body = {"valueInputOption": value_input_option, "data": data}
    result = (
        service.spreadsheets()
        .values()
        .batchUpdate(spreadsheetId=spreadsheet_id, body=body)
        .execute()
    )
    print(f"{(result.get('totalUpdatedCells'))} cells updated.")
    return result
  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: spreadsheet_id, range_name value_input_option and _values)
  batch_update_values(
      "1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k",
      "A1:C2",
      "USER_ENTERED",
      [["F", "B"], ["C", "D"]],
  )

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

הצגת הקוד ב-GitHub

values = [
  [
    # Cell values ...
  ]
  # Additional rows ...
]
data = [
  {
    range:  range_name,
    values: values
  },
  # Additional ranges to update ...
]
batch_update_values = Google::Apis::SheetsV4::BatchUpdateValuesRequest.new(
  data:               data,
  value_input_option: value_input_option
)
result = service.batch_update_values(spreadsheet_id, batch_update_values)
puts "#{result.total_updated_cells} cells updated."

גוף הבקשה לחבילת עדכונים חייב להיות אובייקט BatchUpdateValuesRequest שמכיל ValueInputOption ורשימה של אובייקטים ValueRange (אחד לכל טווח שנכתב). כל אובייקט ValueRange מציין את range, majorDimension ונתוני הקלט שלו.

הוספת ערכים

כדי להוסיף נתונים אחרי טבלת נתונים בגיליון, משתמשים בבקשת spreadsheets.values.append:

Apps Script

sheets/api/spreadsheet_snippets.gs

הצגת הקוד ב-GitHub

/**
 * Appends values to the specified range
 * @param {string} spreadsheetId spreadsheet's ID
 * @param {string} range range of cells in the spreadsheet
 * @param valueInputOption determines how the input should be interpreted
 * @see
 * https://developers.google.com/sheets/api/reference/rest/v4/ValueInputOption
 * @param {list<string>} _values list of rows of values to input
 * @returns {*} spreadsheet with appended values
 */
Snippets.prototype.appendValues = (
  spreadsheetId,
  range,
  valueInputOption,
  _values,
) => {
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];
  try {
    const valueRange = Sheets.newRowData();
    valueRange.values = values;

    const appendRequest = Sheets.newAppendCellsRequest();
    appendRequest.sheetId = spreadsheetId;
    appendRequest.rows = [valueRange];

    const result = Sheets.Spreadsheets.Values.append(
      valueRange,
      spreadsheetId,
      range,
      { valueInputOption: valueInputOption },
    );
    return result;
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log("Failed with error %s", err.message);
  }
};

Java

sheets/snippets/src/main/java/AppendValues.java

הצגת הקוד ב-GitHub

import com.google.api.client.googleapis.json.GoogleJsonError;
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.sheets.v4.Sheets;
import com.google.api.services.sheets.v4.SheetsScopes;
import com.google.api.services.sheets.v4.model.AppendValuesResponse;
import com.google.api.services.sheets.v4.model.ValueRange;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Collections;
import java.util.List;

/* Class to demonstrate the use of Spreadsheet Append Values API */
public class AppendValues {
  /**
   * Appends values to a spreadsheet.
   *
   * @param spreadsheetId    - Id of the spreadsheet.
   * @param range            - Range of cells of the spreadsheet.
   * @param valueInputOption - Determines how input data should be interpreted.
   * @param values           - list of rows of values to input.
   * @return spreadsheet with appended values
   * @throws IOException - if credentials file not found.
   */
  public static AppendValuesResponse appendValues(String spreadsheetId,
                                                  String range,
                                                  String valueInputOption,
                                                  List<List<Object>> values)
      throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
            guides on implementing OAuth2 for your application. */
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Collections.singleton(SheetsScopes.SPREADSHEETS));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Create the sheets API client
    Sheets service = new Sheets.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Sheets samples")
        .build();

    AppendValuesResponse result = null;
    try {
      // Append values to the specified range.
      ValueRange body = new ValueRange()
          .setValues(values);
      result = service.spreadsheets().values().append(spreadsheetId, range, body)
          .setValueInputOption(valueInputOption)
          .execute();
      // Prints the spreadsheet with appended values.
      System.out.printf("%d cells appended.", result.getUpdates().getUpdatedCells());
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      GoogleJsonError error = e.getDetails();
      if (error.getCode() == 404) {
        System.out.printf("Spreadsheet not found with id '%s'.\n", spreadsheetId);
      } else {
        throw e;
      }
    }
    return result;
  }
}

JavaScript

sheets/snippets/sheets_append_values.js

הצגת הקוד ב-GitHub

function appendValues(spreadsheetId, range, valueInputOption, _values, callback) {
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];
  values = _values;
  const body = {
    values: values,
  };
  try {
    gapi.client.sheets.spreadsheets.values.append({
      spreadsheetId: spreadsheetId,
      range: range,
      valueInputOption: valueInputOption,
      resource: body,
    }).then((response) => {
      const result = response.result;
      console.log(`${result.updates.updatedCells} cells appended.`);
      if (callback) callback(response);
    });
  } catch (err) {
    document.getElementById('content').innerText = err.message;
    return;
  }
}

Node.js

sheets/snippets/sheets_append_values.js

הצגת הקוד ב-GitHub

import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Appends values to a spreadsheet.
 * @param {string} spreadsheetId The ID of the spreadsheet to update.
 * @param {string} range The range of cells to append to.
 * @param {string} valueInputOption How the input data should be interpreted.
 * @param {(string[])[]} _values A 2D array of values to append.
 * @return {Promise<object>} The response from the append request.
 */
async function appendValues(spreadsheetId, range, valueInputOption, _values) {
  // Authenticate with Google and get an authorized client.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/spreadsheets',
  });

  // Create a new Sheets API client.
  const service = google.sheets({version: 'v4', auth});

  // The values to append to the spreadsheet.
  let values = [
    [
      // Cell values ...
    ],
    // Additional rows ...
  ];

  // Create the request body.
  const resource = {
    values,
  };

  // Append the values to the spreadsheet.
  const result = await service.spreadsheets.values.append({
    spreadsheetId,
    range,
    valueInputOption,
    resource,
  });

  // Log the number of appended cells.
  console.log(`${result.data.updates.updatedCells} cells appended.`);
  return result;
}

PHP

sheets/snippets/src/SpreadsheetAppendValues.php

הצגת הקוד ב-GitHub

<?php
use Google\Client;
use Google\Service\Sheets;


function appendValues($spreadsheetId, $range, $valueInputOption)
{
    /* Load pre-authorized user credentials from the environment.
       TODO(developer) - See https://developers.google.com/identity for
        guides on implementing OAuth2 for your application. */
    $client = new Google\Client();
    $client->useApplicationDefaultCredentials();
    $client->addScope('https://www.googleapis.com/auth/spreadsheets');
    $service = new Google\Service\Sheets($client);
    try {
        $values = []; //add the values to be appended
        //execute the request
        $body = new Google_Service_Sheets_ValueRange([
            'values' => $values
        ]);
        $params = [
            'valueInputOption' => $valueInputOption
        ];
        $result = $service->spreadsheets_values->append($spreadsheetId, $range, $body, $params);
        printf("%d cells appended.", $result->getUpdates()->getUpdatedCells());
        return $result;
    } catch (Exception $e) {
        // TODO(developer) - handle error appropriately
        echo 'Message: ' . $e->getMessage();
    }

Python

sheets/snippets/sheets_append_values.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError


def append_values(spreadsheet_id, range_name, value_input_option, _values):
  """
  Creates the batch_update the user has access to.
  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()
  # pylint: disable=maybe-no-member
  try:
    service = build("sheets", "v4", credentials=creds)

    values = [
        [
            # Cell values ...
        ],
        # Additional rows ...
    ]
    body = {"values": values}
    result = (
        service.spreadsheets()
        .values()
        .append(
            spreadsheetId=spreadsheet_id,
            range=range_name,
            valueInputOption=value_input_option,
            body=body,
        )
        .execute()
    )
    print(f"{(result.get('updates').get('updatedCells'))} cells appended.")
    return result

  except HttpError as error:
    print(f"An error occurred: {error}")
    return error


if __name__ == "__main__":
  # Pass: spreadsheet_id, range_name value_input_option and _values)
  append_values(
      "1CM29gwKIzeXsAppeNwrc8lbYaVMmUclprLuLYuHog4k",
      "A1:C2",
      "USER_ENTERED",
      [["F", "B"], ["C", "D"]],
  )

Ruby

sheets/snippets/lib/spreadsheet_snippets.rb

הצגת הקוד ב-GitHub

values = [
  [
    # Cell values ...
  ],
  # Additional rows ...
]
value_range = Google::Apis::SheetsV4::ValueRange.new(values: values)
result = service.append_spreadsheet_value(spreadsheet_id,
                                          range_name,
                                          value_range,
                                          value_input_option: value_input_option)
puts "#{result.updates.updated_cells} cells appended."

גוף בקשת העדכון חייב להיות אובייקט ValueRange, אבל שדה החובה היחיד הוא values. אם מציינים את הערך range, הוא חייב להתאים לטווח בכתובת ה-URL. ב-ValueRange, אפשר לציין את majorDimension. כברירת מחדל, נעשה שימוש ב-ROWS. אם מציינים את COLUMNS, כל מערך פנימי נכתב בעמודה במקום בשורה.

הערה: הפרמטר majorDimension לא קובע אם הנתונים יתווספו לטבלה כשורה או כעמודה. הנתונים תמיד מתווספים לשורות הבאות. הפרמטר קובע רק איך נתוני הקלט נקראים.

טווח הקלט משמש לחיפוש נתונים קיימים ולמציאת 'טבלה' בטווח הזה. הערכים מתווספים לשורה הבאה בטבלה, החל מהעמודה הראשונה בטבלה. לדוגמה, נניח שיש לכם את הנתונים הבאים Sheet1:

	A	ב	C	D	E
1	x	y	z
2	x	y	z
3
4		x	y
5			y	z
6		x	y	z
7

יש שני גיליונות בגיליון האלקטרוני: A1:C2 ו-B4:D6. הערכים המצורפים יתחילו ב-B7 לכל ערכי הקלט הבאים של range:

• ‫Sheet1, כי הוא יבדוק את כל הנתונים בגיליון ויקבע שהטבלה ב-B4:D6 היא הטבלה האחרונה.
• B4 או C5:D5, כי שניהם נמצאים בטבלה B4:D6.
• ‫B2:D4, כי הטבלה האחרונה בטווח היא הטבלה B4:D6 (למרות שהיא מכילה גם את הטבלה A1:C2).
• ‫A3:G10, כי הטבלה האחרונה בטווח היא הטבלה B4:D6 (למרות שהיא מתחילה לפני ומסתיימת אחרי).

הקלט הבא range לא התחיל לכתוב בשעה B7:

• ‫A1 יתחיל לכתוב ב-A3, כי זה נמצא בטבלה A1:C2.
• ‫E4 יתחיל לכתוב ב-E4, כי הוא לא נמצא באף טבלה. (A4 יתחיל לכתוב גם ב-A4 מאותן סיבות).

בנוסף, אפשר לבחור אם רוצים להחליף נתונים קיימים אחרי טבלה או להוסיף שורות חדשות לנתונים החדשים. כברירת מחדל, הקלט מחליף את הנתונים אחרי הטבלה. כדי לכתוב את הנתונים החדשים בשורות חדשות, משתמשים ב-InsertDataOption ומציינים insertDataOption=INSERT_ROWS.

מידע נוסף על מגבלות התאים והשורות ב-Sheets זמין במאמר קבצים שאפשר לאחסן ב-Google Drive.