بالإضافة إلى بيانات القيمة الواردة في الخلايا، يتضمن جدول البيانات العديد من أنواع البيانات الأخرى، مثل:
- الأبعاد
- تنسيقات الخلايا وحدودها
- النطاقات المُعنونة
- النطاقات المحمية
- التنسيق المشروط
هذه بعض أنواع البيانات العديدة التي تتحكم في
مظهر جدول البيانات وتشغيله. تتيح لك طريقة spreadsheets.batchUpdate
تعديل
أي من تفاصيل جدول البيانات هذه. يتم تجميع التغييرات في دفعة بحيث إذا لم ينجح أحد الطلبات، فلا تتم كتابة أي من التغييرات الأخرى (التي يحتمل أن تكون تابعة).
توضّح هذه الصفحة أساسيات استخدام إجراء spreadsheets.batchUpdate
. إذا كنت بحاجة إلى قراءة بيانات قيم الخلية وكتابتها، يمكنك أيضًا استخدام المرجع
spreadsheets.values
الموضّح في قراءة قيم الخلايا وكتابتها.
فئات العمليات
يمكن تجميع العمليات الخاصة التي يدعمها spreadsheets.batchUpdate
في الفئات الواسعة التالية:
الفئة | الوصف |
---|---|
إضافة (ونسخة طبق الأصل) | إضافة عناصر جديدة (يعتمد ذلك أحيانًا على العناصر القديمة، كما في الطلبات المكرّرة). |
تحديث (وضبط) | تعديل خصائص معيّنة لأحد العناصر، مع ترك السمات القديمة كما هي عادةً (بينما يحلّ طلب "Set" محلّ البيانات السابقة) |
حذف | إزالة العناصر. |
تُستخدم هذه الفئات في القسم التالي لوصف سلوك عمليات محددة.
عمليات التحديث المجمّع
تعمل الطريقة spreadsheets.batchUpdate
من خلال أخذ كائن
طلب واحد أو أكثر، يحدّد كل عنصر نوعًا واحدًا من الطلبات التي يتم تنفيذها. هناك العديد من
أنواع الطلبات المختلفة. إليك تقسيمًا لأنواع الطلبات،
مجمعة في فئات مختلفة.
هناك أيضًا بعض الطلبات الإضافية التي تحاكي إجراءات المستخدم لمعالجة البيانات:
- 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
.