صفحات گسترده می توانند چندین صفحه داشته باشند که هر صفحه دارای هر تعداد سطر یا ستون باشد. سلول مکانی در تقاطع یک سطر و ستون خاص است و ممکن است حاوی یک مقدار داده باشد. 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 در نظر بگیرید که به شکل زیر است:
| الف | ب | سی | D | 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 ذخیره کنید مراجعه کنید.