صفحات گسترده میتوانند چندین صفحه داشته باشند که هر صفحه میتواند شامل هر تعداد سطر یا ستون باشد. یک سلول ، مکانی در تقاطع یک سطر و ستون خاص است و ممکن است حاوی یک مقدار داده باشد. 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 استفاده کنید:
اسکریپت برنامهها
جاوا
جاوا اسکریپت
نود جی اس
پی اچ پی
پایتون
روبی
پاسخ به این درخواست به صورت یک شیء ValueRange برگردانده میشود.
خواندن چندین محدوده
برای خواندن چندین محدودهی ناپیوسته از مقادیر از یک صفحهگسترده، از درخواست spreadsheets.values.batchGet استفاده کنید که به شما امکان میدهد چندین محدوده را برای بازیابی مشخص کنید:
اسکریپت برنامهها
جاوا
جاوا اسکریپت
نود جی اس
پی اچ پی
پایتون
روبی
پاسخ به این درخواست به صورت یک شیء 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 استفاده کنید:
اسکریپت برنامهها
جاوا
جاوا اسکریپت
نود جی اس
پی اچ پی
پایتون
روبی
بدنه درخواست بهروزرسانی باید یک شیء ValueRange باشد، اگرچه تنها فیلد مورد نیاز values است. اگر range مشخص شده باشد، باید با range موجود در URL مطابقت داشته باشد. در ValueRange ، میتوانید به صورت اختیاری majorDimension آن را مشخص کنید. به طور پیشفرض، ROWS استفاده میشود. اگر COLUMNS مشخص شده باشد، هر آرایه داخلی به جای یک ردیف، در یک ستون نوشته میشود.
هنگام بهروزرسانی، مقادیری که دادهای ندارند، نادیده گرفته میشوند. برای پاک کردن دادهها، از یک رشته خالی ("") استفاده کنید.
نوشتن چندین محدوده
اگر میخواهید چندین محدوده ناپیوسته بنویسید، میتوانید از درخواست spreadsheets.values.batchUpdate استفاده کنید:
اسکریپت برنامهها
جاوا
جاوا اسکریپت
نود جی اس
پی اچ پی
پایتون
روبی
بدنه درخواست بهروزرسانی دستهای باید یک شیء BatchUpdateValuesRequest باشد که شامل یک ValueInputOption و لیستی از اشیاء ValueRange (یکی برای هر محدوده نوشته شده) است. هر شیء ValueRange range ، majorDimension و دادههای ورودی خود را مشخص میکند.
مقادیر را اضافه کنید
برای افزودن دادهها به بعد از جدول دادهها در یک برگه، از درخواست spreadsheets.values.append استفاده کنید:
اسکریپت برنامهها
جاوا
جاوا اسکریپت
نود جی اس
پی اچ پی
پایتون
روبی
بدنه درخواست بهروزرسانی باید یک شیء 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 ذخیره کنید مراجعه کنید.