این سند اصول اولیه استفاده از متد spreadsheets.batchUpdate را در منبع spreadsheets شرح میدهد.
گذشته از دادههای مقداری موجود در سلولهای آن، یک صفحه گسترده شامل انواع دیگری از دادهها نیز میشود، مانند:
- ابعاد
- قالبها و حاشیههای سلول
- محدودههای نامگذاری شده
- محدودههای حفاظتشده
- قالببندی شرطی
اینها برخی از انواع دادههایی هستند که ظاهر و عملکرد یک صفحه گسترده را کنترل میکنند. متد spreadsheets.batchUpdate به شما امکان میدهد هر یک از این جزئیات صفحه گسترده را بهروزرسانی کنید. تغییرات در یک دسته گروهبندی میشوند، به طوری که اگر یک درخواست ناموفق باشد، هیچ یک از تغییرات دیگر (که به طور بالقوه وابسته هستند) نوشته نمیشوند.
اگر نیاز به خواندن و نوشتن دادههای مربوط به مقدار سلول دارید، میتوانید از منبع spreadsheets.values نیز همانطور که در بخش «خواندن و نوشتن مقادیر سلول» توضیح داده شده است، استفاده کنید.
انواع عملیات
عملیات خاص پشتیبانی شده توسط متد spreadsheets.batchUpdate را میتوان به انواع عملیات کلی زیر گروهبندی کرد:
| دسته بندی | توضیحات |
|---|---|
| اضافه کردن (و کپی کردن ) | اشیاء جدید اضافه کنید (گاهی اوقات بر اساس اشیاء قدیمی، مانند درخواستهای تکراری). |
| بهروزرسانی (و تنظیم ) | بهروزرسانی ویژگیهای خاصی از یک شیء، معمولاً بدون تغییر ویژگیهای قدیمی (در حالی که درخواست Set دادههای قبلی را بازنویسی میکند). |
| حذف | اشیاء را بردارید. |
این دسته بندی ها در بخش بعدی برای توصیف رفتار عملیات خاص استفاده می شوند.
عملیات بهروزرسانی دستهای
متد spreadsheets.batchUpdate با دریافت یک یا چند شیء Request کار میکند که هر کدام نوع درخواستی را برای اجرا مشخص میکنند. جدول زیر انواع درخواستهای بهروزرسانی دستهای را که بر اساس شیء منبع و نوع عملیات گروهبندی شدهاند، فهرست میکند:
درخواستهای دستکاری دادهها
همچنین برخی درخواستهای اضافی وجود دارد که اقدامات کاربر را برای دستکاری دادهها تقلید میکنند:
| درخواست | توضیحات |
|---|---|
AutoFillRequest | به طور خودکار دادههای بیشتری را بر اساس دادههای موجود پر میکند. |
CopyPasteRequest | دادهها را از یک ناحیه کپی کرده و در ناحیه دیگر جایگذاری میکند. |
CutPasteRequest | دادهها را از یک ناحیه برش داده و در ناحیه دیگری جایگذاری میکند. |
DeleteDuplicatesRequest | ردیفهای حاوی مقادیر تکراری را در ستونهای مشخصشده از یک محدوده سلولی حذف میکند. |
FindReplaceRequest | موارد تکرار یک متن را پیدا کرده و با متن دیگری جایگزین میکند. |
PasteDataRequest | دادهها (HTML یا جدا شده) را در یک برگه جایگذاری میکند. |
RandomizeRangeRequest | ترتیب ردیفها را در یک محدوده تصادفی میکند. |
SortRangeRequest | دادهها را در یک محدوده مرتب میکند. |
TextToColumnsRequest | یک ستون متن را به چندین ستون متن تبدیل میکند. |
TrimWhitespaceRequest | سلولهای دارای فضای خالی (مانند فاصله، تب یا خط جدید) را حذف میکند. |
برای کسب اطلاعات بیشتر در مورد محدودیتهای سلول و ردیف در Google Sheets، به فایلهایی که میتوانید در Google Drive ذخیره کنید مراجعه کنید.
استفاده از ماسکهای فیلد برای بهروزرسانی فیلدهای خاص
بسیاری از درخواستهای بهروزرسانی نیاز به FieldMask دارند. Field Mask فهرستی از فیلدها است که با کاما از هم جدا شده و برای نشان دادن فیلدهایی در یک شیء که باید بهروزرسانی شوند، استفاده میشود، در حالی که سایر فیلدها بدون تغییر باقی میمانند. استفاده از Field Mask از رونویسی تصادفی فیلدهایی که در درخواست مشخص نشدهاند، جلوگیری میکند.
برای اطلاعات بیشتر در مورد ماسکهای میدانی، به بهروزرسانی با ماسک میدانی مراجعه کنید.
نمونه کد زیر نحوه استفاده از UpdateSpreadsheetPropertiesRequest را برای بهروزرسانی فقط عنوان یک صفحه گسترده نشان میدهد:
درخواست
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
درخواست بدنه
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}TITLE با عنوان جدید صفحه گسترده جایگزین کنید.
بهروزرسانی دستهای پاسخها
هنگام بهروزرسانی یک صفحه گسترده، برخی از انواع درخواستها ممکن است پاسخهایی را برگردانند. این پاسخها در یک آرایه برگردانده میشوند و هر پاسخ، اندیس مشابهی با درخواست مربوطه دارد. برخی از درخواستها پاسخی ندارند و برای آنها پاسخ خالی است.
معمولاً درخواستهای «افزودن» پاسخهایی دارند که اطلاعاتی مانند شناسه شیء اضافه شده را برمیگردانند. برای فهرست پاسخهای پشتیبانیشده، به Responses مراجعه کنید.
نمونه کد: صفحه گسترده بهروزرسانی دستهای
نمونه کد زیر نحوه انجام این اقدامات را نشان میدهد:
- عنوان صفحه گسترده را با استفاده از متغیر
titleبهروزرسانی کنید. - با استفاده از متغیرهای
findوreplacementمقادیر سلولها را در صفحه گسترده پیدا و جایگزین کنید.