خواندن & مقادیر سلول را بنویسید

صفحات گسترده می‌توانند چندین صفحه داشته باشند که هر صفحه می‌تواند شامل هر تعداد سطر یا ستون باشد. یک سلول ، مکانی در تقاطع یک سطر و ستون خاص است و ممکن است حاوی یک مقدار داده باشد. API گوگل شیت، منبع spreadsheets.values ​​را برای فعال کردن خواندن و نوشتن مقادیر ارائه می‌دهد.

این صفحه اصول اولیه استفاده از منبع spreadsheets.values ​​را شرح می‌دهد. اگر نیاز به درج ردیف یا به‌روزرسانی قالب‌بندی و سایر ویژگی‌ها در یک برگه دارید، باید از متد spreadsheets.batchUpdate که در بخش به‌روزرسانی صفحات گسترده توضیح داده شده است، استفاده کنید.

روش‌ها

منبع spreadsheets.values ​​متدهای زیر را برای خواندن و نوشتن مقادیر ارائه می‌دهد که هر کدام برای یک کار خاص هستند:

دسترسی به محدوده خواندن نوشتن
برد تکی spreadsheets.values.get spreadsheets.values.update
چندین محدوده spreadsheets.values.batchGet spreadsheets.values.batchUpdate
ضمیمه کردن spreadsheets.values.append

به طور کلی، ایده خوبی است که چندین خواندن یا به‌روزرسانی را با متدهای batchGet و batchUpdate (به ترتیب) ترکیب کنید، زیرا این کار باعث بهبود کارایی می‌شود.

می‌توانید نمونه‌هایی از هر یک از این روش‌ها را در صفحات نمونه‌های خواندن پایه و نوشتن پایه بیابید. برای مشاهده همه نمونه‌ها، به صفحه مرور کلی نمونه‌ها مراجعه کنید.

بخوانید

برای خواندن مقادیر داده از یک برگه، به شناسه صفحه گسترده و نماد A1 برای محدوده نیاز دارید. مشخص کردن محدوده بدون شناسه صفحه ( A1:B2 ) به این معنی است که درخواست در اولین برگه در صفحه گسترده اجرا می‌شود. برای اطلاعات بیشتر در مورد شناسه‌های صفحه گسترده و نماد A1، به بررسی اجمالی API صفحات Google مراجعه کنید.

چندین پارامتر اختیاری کوئری، فرمت خروجی را کنترل می‌کنند:

پارامتر فرمت مقدار پیش‌فرض
majorDimension ردیف‌ها
valueRenderOption مقدار قالب‌بندی‌شده
dateTimeRenderOption شماره سریال

توجه داشته باشید که فقط در صورتی باید dateTimeRenderOption استفاده کنید که valueRenderOption FORMATTED_VALUE نباشد.

هیچ محدودیت مشخصی برای مقدار داده‌های برگشتی وجود ندارد. خطاها هیچ داده‌ای برنمی‌گردانند. ردیف‌ها و ستون‌های خالی انتهایی حذف می‌شوند.

روش‌های دریافت تکی و دسته‌ای در زیر توضیح داده شده‌اند. برای نمونه‌هایی از عملیات خواندن پایه، به بخش خواندن پایه مراجعه کنید.

خواندن یک محدوده واحد

برای خواندن یک محدوده واحد از مقادیر از یک صفحه گسترده، از درخواست spreadsheets.values.get استفاده کنید:

اسکریپت برنامه‌ها

sheets/api/spreadsheet_snippets.gs
/**
 * 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);
  }
};

جاوا

sheets/snippets/src/main/java/GetValues.java
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;
  }
}

جاوا اسکریپت

sheets/snippets/sheets_get_values.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_get_values.js
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;
}

پی اچ پی

sheets/snippets/src/SpreadsheetGetValues.php
<?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();
        }
    }

پایتون

sheets/snippets/sheets_get_values.py
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")

روبی

sheets/snippets/lib/spreadsheet_snippets.rb
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.batchGet استفاده کنید که به شما امکان می‌دهد چندین محدوده را برای بازیابی مشخص کنید:

اسکریپت برنامه‌ها

sheets/api/spreadsheet_snippets.gs
/**
 * 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);
  }
};

جاوا

sheets/snippets/src/main/java/BatchGetValues.java
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;
  }
}

جاوا اسکریپت

sheets/snippets/sheets_batch_get_values.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_batch_get_values.js
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'
  ];

پی اچ پی

sheets/snippets/src/SpreadsheetBatchGetValues.php
<?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();
          }
        }

پایتون

sheets/snippets/sheets_batch_get_values.py
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")

روبی

sheets/snippets/lib/spreadsheet_snippets.rb
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، به مرور کلی API صفحات گوگل مراجعه کنید.

به‌روزرسانی‌ها به یک پارامتر معتبر ValueInputOption نیاز دارند. برای به‌روزرسانی‌های تکی، این یک پارامتر پرس‌وجوی الزامی است. برای به‌روزرسانی‌های دسته‌ای، این پارامتر در بدنه درخواست الزامی است. ValueInputOption نحوه تفسیر داده‌های ورودی و تجزیه یا عدم تجزیه رشته‌های ورودی را کنترل می‌کند، همانطور که در جدول زیر توضیح داده شده است:

ValueInputOption توضیحات
RAW ورودی تجزیه نمی‌شود و به صورت رشته درج می‌شود. برای مثال، ورودی "=1+2" رشته را در سلول قرار می‌دهد، نه فرمول "=1+2" را. (مقادیر غیر رشته‌ای مانند بولی یا اعداد همیشه به صورت RAW پردازش می‌شوند.)
USER_ENTERED ورودی دقیقاً مانند زمانی که در رابط کاربری Sheets وارد می‌شود، تجزیه و تحلیل می‌شود. برای مثال، "1 مارس 2016" به یک تاریخ تبدیل می‌شود و "=1+2" به یک فرمول تبدیل می‌شود. قالب‌ها نیز قابل استنباط هستند، بنابراین "100.15 دلار" به یک عدد با قالب‌بندی ارزی تبدیل می‌شود.

روش‌های به‌روزرسانی تکی و دسته‌ای در زیر شرح داده شده‌اند. برای نمونه‌هایی از عملیات نوشتن پایه، به Basic writing مراجعه کنید.

نوشتن در یک محدوده واحد

برای نوشتن داده‌ها در یک محدوده واحد، از درخواست spreadsheets.values.update استفاده کنید:

اسکریپت برنامه‌ها

sheets/api/spreadsheet_snippets.gs
/**
 * 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);
  }
};

جاوا

sheets/snippets/src/main/java/UpdateValues.java
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;
  }
}

جاوا اسکریپت

sheets/snippets/sheets_update_values.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_update_values.js
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;
}

پی اچ پی

sheets/snippets/src/SpreadsheetUpdateValues.php
<?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();
          }
    }

پایتون

sheets/snippets/sheets_update_values.py
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"]],
  )

روبی

sheets/snippets/lib/spreadsheet_snippets.rb
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 مشخص شده باشد، باید با range موجود در URL مطابقت داشته باشد. در ValueRange ، می‌توانید به صورت اختیاری majorDimension آن را مشخص کنید. به طور پیش‌فرض، ROWS استفاده می‌شود. اگر COLUMNS مشخص شده باشد، هر آرایه داخلی به جای یک ردیف، در یک ستون نوشته می‌شود.

هنگام به‌روزرسانی، مقادیری که داده‌ای ندارند، نادیده گرفته می‌شوند. برای پاک کردن داده‌ها، از یک رشته خالی ("") استفاده کنید.

نوشتن چندین محدوده

اگر می‌خواهید چندین محدوده ناپیوسته بنویسید، می‌توانید از درخواست spreadsheets.values.batchUpdate استفاده کنید:

اسکریپت برنامه‌ها

sheets/api/spreadsheet_snippets.gs
/**
 * 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);
  }
};

جاوا

sheets/snippets/src/main/java/BatchUpdateValues.java
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;
  }
}

جاوا اسکریپت

sheets/snippets/sheets_batch_update_values.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_batch_update_values.js
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;
}

پی اچ پی

sheets/snippets/src/SpreadsheetBatchUpdateValues.php
<?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();
          }
    }

پایتون

sheets/snippets/sheets_batch_update_values.py
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"]],
  )

روبی

sheets/snippets/lib/spreadsheet_snippets.rb
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 استفاده کنید:

اسکریپت برنامه‌ها

sheets/api/spreadsheet_snippets.gs
/**
 * 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);
  }
};

جاوا

sheets/snippets/src/main/java/AppendValues.java
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;
  }
}

جاوا اسکریپت

sheets/snippets/sheets_append_values.js
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;
  }
}

نود جی اس

sheets/snippets/sheets_append_values.js
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;
}

پی اچ پی

sheets/snippets/src/SpreadsheetAppendValues.php
<?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();
    }

پایتون

sheets/snippets/sheets_append_values.py
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"]],
  )

روبی

sheets/snippets/lib/spreadsheet_snippets.rb
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 مشخص شده باشد، باید با range موجود در URL مطابقت داشته باشد. در ValueRange ، می‌توانید به صورت اختیاری majorDimension آن را مشخص کنید. به طور پیش‌فرض، ROWS استفاده می‌شود. اگر COLUMNS مشخص شده باشد، هر آرایه داخلی به جای یک ردیف، در یک ستون نوشته می‌شود.

محدوده ورودی برای جستجوی داده‌های موجود و یافتن یک "جدول" در آن محدوده استفاده می‌شود. مقادیر به ردیف بعدی جدول، با شروع از ستون اول جدول، اضافه می‌شوند. به عنوان مثال، Sheet1 را در نظر بگیرید که به شکل زیر است:

الف ب سی دی ای
۱ ایکس ی ز
۲ ایکس ی ز
۳
۴ ایکس ی
۵ ی ز
۶ ایکس ی ز
۷

دو جدول در این برگه وجود دارد: A1:C2 و B4:D6 . مقادیر اضافه شده برای تمام ورودی‌های range زیر از B7 شروع می‌شوند:

  • 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 ذخیره کنید مراجعه کنید.