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