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