يوضّح هذا المستند أساسيات استخدام طريقة
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"، يُرجى الاطّلاع على الملفات التي يمكنك تخزينها في 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.