يصف هذا المستند أساسيات استخدام طريقة
spreadsheets.batchUpdate
في مصدر
spreadsheets.
بالإضافة إلى بيانات القيم الواردة في خلايا جدول البيانات، يتضمّن جدول البيانات أنواعًا أخرى كثيرة من البيانات، مثل:
- الأبعاد
- تنسيقات الخلايا وحدودها
- النطاقات المُعنونة
- النطاقات المحمية
- التنسيق المشروط
هذه بعض أنواع البيانات الكثيرة التي تتحكّم في مظهر جدول البيانات وطريقة عمله. تتيح لك طريقة spreadsheets.batchUpdate تعديل أيّ من تفاصيل جدول البيانات هذه. يتم تجميع التغييرات في دفعة واحدة، لذا إذا لم ينجح أحد الطلبات، لن يتم حفظ أيّ من التغييرات الأخرى (التي قد تكون معتمِدة عليه).
إذا كنت بحاجة إلى قراءة بيانات قيم الخلايا وكتابتها، يمكنك أيضًا استخدام الـ
spreadsheets.values
مصدر كما هو موضّح في قراءة قيم الخلايا وكتابتها.
أنواع العمليات
يمكن تجميع العمليات المحدّدة التي تتيحها طريقة spreadsheets.batchUpdate في أنواع العمليات العامة التالية:
| الفئة | الوصف |
|---|---|
| إضافة (وإنشاء نسخة طبق الأصل) | إضافة عناصر جديدة (تستند أحيانًا إلى عناصر قديمة، كما في طلبات "إنشاء نسخة طبق الأصل") |
| تعديل (وضبط) | تعديل خصائص معيّنة لعنصر، مع ترك الخصائص القديمة كما هي عادةً (بينما يلغي طلب "ضبط" البيانات السابقة) |
| حذف | إزالة العناصر |
تُستخدَم هذه الفئات في القسم التالي لوصف سلوك عمليات معيّنة.
عمليات التعديل المجمّع
تعمل طريقة spreadsheets.batchUpdate من خلال أخذ عنصر واحد أو أكثر من عناصر
Request
، ويحدّد كل عنصر نوعًا واحدًا من الطلبات التي يجب تنفيذها. يسرد الجدول التالي أنواع طلبات التعديل المجمّع، مجمّعة حسب عنصر المصدر ونوع العملية:
طلبات معالجة البيانات
تتوفّر أيضًا بعض الطلبات الإضافية التي تحاكي إجراءات المستخدم لمعالجة البيانات:
| طلب | الوصف |
|---|---|
AutoFillRequest |
تعبئة المزيد من البيانات تلقائيًا استنادًا إلى البيانات الحالية |
CopyPasteRequest |
نسخ البيانات من منطقة ولصقها في منطقة أخرى |
CutPasteRequest |
قصّ البيانات من منطقة ولصقها في منطقة أخرى |
DeleteDuplicatesRequest |
إزالة الصفوف التي تحتوي على قيم مكرّرة في أعمدة محدّدة من نطاق خلايا |
FindReplaceRequest |
البحث عن بعض النصوص واستبدالها بنصوص أخرى |
PasteDataRequest |
لصق البيانات (بتنسيق HTML أو بتنسيق مفصول) في ورقة بيانات |
RandomizeRangeRequest |
تغيير ترتيب الصفوف عشوائيًا في نطاق |
SortRangeRequest |
فرز البيانات في نطاق |
TextToColumnsRequest |
تحويل عمود نصي إلى عدة أعمدة نصية |
TrimWhitespaceRequest |
إزالة المسافات البيضاء (مثل المسافات أو علامات الجدولة أو الأسطر الجديدة) من الخلايا |
لمزيد من المعلومات عن الحدود القصوى للخلايا والصفوف في "جداول بيانات Google"، يُرجى الاطّلاع على الملفات التي يمكنك تخزينها في Google Drive.
استخدام أقنعة الحقول لتعديل حقول معيّنة
تتطلّب العديد من طلبات التعديل توفّر FieldMask. قناع الحقل هو قائمة مفصولة بفواصل من الحقول تُستخدَم للإشارة إلى الحقول المطلوب تعديلها في عنصر، مع ترك جميع الحقول الأخرى بدون تغيير. يمنع استخدام قناع الحقل الكتابة فوق الحقول التي لم يتم تحديدها في الطلب عن طريق الخطأ.
لمزيد من المعلومات عن أقنعة الحقول، يُرجى الاطّلاع على التعديل باستخدام قناع حقل.
يوضّح نموذج الرمز البرمجي التالي كيفية استخدام الـ
UpdateSpreadsheetPropertiesRequest
لتعديل عنوان جدول بيانات فقط:
طلب
POST https://sheets.googleapis.com/v4/spreadsheets/spreadsheetId:batchUpdate
نص الطلب
{
"requests": [{
"updateSpreadsheetProperties": {
"properties": {"title": "TITLE"},
"fields": "title"
}
}]
}استبدِل TITLE بالعنوان الجديد لجدول البيانات.
ردود التعديل المجمّع
عند تعديل جدول بيانات، قد تعرض بعض أنواع الطلبات ردودًا. يتم عرض هذه الردود في مصفوفة، ويشغل كل ردّ الفهرس نفسه الذي يشغله الطلب المقابل. لا تتضمّن بعض الطلبات ردودًا، ويكون الردّ فارغًا في هذه الحالة.
عادةً ما تتضمّن طلبات "الإضافة" ردودًا تعرض معلومات مثل رقم تعريف العنصر الذي تمت إضافته. للاطّلاع على قائمة الردود المتوافقة، يُرجى الاطّلاع على
Responses.
عينة تعليمات برمجية: التعديل المجمّع لجدول بيانات
توضح عينة التعليمات البرمجية التالية كيفية تنفيذ هذه الإجراءات:
- تعديل عنوان جدول البيانات باستخدام المتغيّر
title - البحث عن قيم الخلايا واستبدالها في جدول البيانات باستخدام المتغيّرَين
findوreplacement