صفحات گسترده می توانند چندین صفحه داشته باشند که هر صفحه دارای هر تعداد سطر یا ستون باشد. سلول مکانی در تقاطع یک سطر و ستون خاص است و ممکن است حاوی یک مقدار داده باشد. Google Sheets 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 | ROWS |
valueRenderOption | FORMATTED_VALUE |
dateTimeRenderOption | SERIAL_NUMBER |
توجه داشته باشید که فقط در صورتی باید از dateTimeRenderOption
استفاده کنید که valueRenderOption
FORMATTED_VALUE
نباشد.
هیچ محدودیت صریحی برای مقدار داده های برگشتی وجود ندارد. خطاها هیچ داده ای را برمی گرداند. سطرها و ستون های انتهایی خالی حذف می شوند.
روش های تکی و دسته ای در زیر توضیح داده شده است. برای نمونههایی از عملیات خواندن پایه، خواندن پایه را ببینید.
یک محدوده را بخوانید
برای خواندن یک محدوده از مقادیر از یک صفحه گسترده، از یک درخواست spreadsheets.values.get
استفاده کنید:
اسکریپت برنامه ها
جاوا
جاوا اسکریپت
Node.js
PHP
پایتون
روبی
پاسخ به این درخواست به عنوان یک شی ValueRange
برگردانده می شود.
محدوده های متعدد را بخوانید
برای خواندن چندین محدوده مقادیر ناپیوسته از یک صفحه گسترده، از یک درخواست spreadsheets.values.batchGet
استفاده کنید که به شما امکان می دهد چندین محدوده را برای بازیابی مشخص کنید:
اسکریپت برنامه ها
جاوا
جاوا اسکریپت
Node.js
PHP
پایتون
روبی
پاسخ به این درخواست به عنوان یک شیء BatchGetValuesResponse
برگردانده می شود که حاوی spreadsheetId
و لیستی از اشیاء ValueRange
است.
بنویسید
برای نوشتن در یک برگه، به شناسه صفحه گسترده، محدوده سلولها در نماد A1، و دادههایی که میخواهید در یک شی بدنه درخواستی مناسب بنویسید، نیاز دارید. برای اطلاعات بیشتر درباره شناسههای صفحهگسترده و نماد A1، به نمای کلی API کاربرگنگار Google مراجعه کنید.
بهروزرسانیها به یک پارامتر ValueInputOption
معتبر نیاز دارند. برای به روز رسانی های منفرد، این یک پارامتر پرس و جو ضروری است. برای به روز رسانی دسته ای، این پارامتر در بدنه درخواست مورد نیاز است. ValueInputOption
کنترل می کند که چگونه داده های ورودی باید تفسیر شوند و آیا رشته های ورودی تجزیه می شوند یا نه، همانطور که در جدول زیر توضیح داده شده است:
ValueInputOption | توضیحات |
---|---|
RAW | ورودی تجزیه نمی شود و به عنوان یک رشته درج می شود. به عنوان مثال، ورودی "=1+2" رشته را قرار می دهد، نه فرمول، "=1+2" را در سلول. (مقادیر غیر رشته ای مانند بولی ها یا اعداد همیشه به صورت RAW در نظر گرفته می شوند.) |
USER_ENTERED | ورودی دقیقاً به گونهای تجزیه میشود که گویی وارد رابط کاربر Sheets شده است. به عنوان مثال، "1 مارس 2016" به یک تاریخ تبدیل می شود و "=1+2" به یک فرمول تبدیل می شود. فرمت ها را نیز می توان استنباط کرد، بنابراین "100.15 دلار" با قالب بندی ارز تبدیل به عددی می شود. |
روش های به روز رسانی تکی و دسته ای در زیر توضیح داده شده است. برای نمونههایی از عملیات نوشتن پایه، نوشتن پایه را ببینید.
در یک محدوده بنویسید
برای نوشتن داده در یک محدوده، از درخواست spreadsheets.values.update
استفاده کنید:
اسکریپت برنامه ها
جاوا
جاوا اسکریپت
Node.js
PHP
پایتون
روبی
بدنه درخواست بهروزرسانی باید یک شی ValueRange
باشد، اگرچه تنها فیلد مورد نیاز values
است. اگر range
مشخص شده باشد، باید با محدوده موجود در URL مطابقت داشته باشد. در ValueRange
می توانید به صورت اختیاری majorDimension
آن را مشخص کنید. به طور پیش فرض از ROWS
استفاده می شود. اگر COLUMNS
مشخص شده باشد، هر آرایه داخلی به جای یک ردیف در یک ستون نوشته می شود.
هنگام به روز رسانی، مقادیر بدون داده رد می شوند. برای پاک کردن داده ها، از یک رشته خالی ("") استفاده کنید.
چندین محدوده بنویسید
اگر می خواهید چندین محدوده ناپیوسته بنویسید، می توانید از یک درخواست spreadsheets.values.batchUpdate
استفاده کنید:
اسکریپت برنامه ها
جاوا
جاوا اسکریپت
Node.js
PHP
پایتون
روبی
بدنه درخواست بهروزرسانی دستهای باید یک شی BatchUpdateValuesRequest
باشد که حاوی یک ValueInputOption
و فهرستی از اشیاء ValueRange
(یکی برای هر محدوده نوشته شده) است. هر شی ValueRange
range
، majorDimension
و داده های ورودی خود را مشخص می کند.
اضافه کردن مقادیر
برای اضافه کردن دادهها پس از جدول دادهها در یک برگه، از درخواست spreadsheets.values.append
استفاده کنید:
اسکریپت برنامه ها
جاوا
جاوا اسکریپت
Node.js
PHP
پایتون
روبی
بدنه درخواست بهروزرسانی باید یک شی ValueRange
باشد، اگرچه تنها فیلد مورد نیاز values
است. اگر range
مشخص شده باشد، باید با محدوده موجود در URL مطابقت داشته باشد. در ValueRange
می توانید به صورت اختیاری majorDimension
آن را مشخص کنید. به طور پیش فرض از ROWS
استفاده می شود. اگر COLUMNS
مشخص شده باشد، هر آرایه داخلی به جای یک ردیف در یک ستون نوشته می شود.
محدوده ورودی برای جستجوی داده های موجود و یافتن یک "جدول" در آن محدوده استفاده می شود. مقادیر به سطر بعدی جدول اضافه می شوند و از ستون اول جدول شروع می شوند. برای مثال، Sheet1
در نظر بگیرید که به شکل زیر است:
الف | ب | سی | دی | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
2 جدول در برگه وجود دارد: 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
را مشخص کنید.
برای کسب اطلاعات بیشتر درباره محدودیتهای سلول و ردیف در کاربرگنگار، به فایلهایی که میتوانید در Google Drive ذخیره کنید مراجعه کنید.