يمكن أن تحتوي جداول البيانات على أوراق متعددة، حيث تحتوي كل ورقة على أي عدد من الصفوف
أو الأعمدة. الخلية هي موقع في
تقاطع صف وعمود معينين، وقد يحتوي على قيمة بيانات. تشير رسالة الأشكال البيانية
توفر واجهة برمجة التطبيقات Google Sheets API
spreadsheets.values
إلى تمكين قراءة القيم وكتابتها.
توضّح هذه الصفحة أساسيات استخدام المرجع spreadsheets.values
. في حال حذف
تحتاج إلى إدراج صفوف أو تحديث التنسيق والخصائص الأخرى في
ورقة البيانات، فيجب عليك استخدام
spreadsheets.batchUpdate
الموضحة في تحديث جداول البيانات.
الطُرق
مرجع spreadsheets.values
الطرق التالية لقراءة القيم وكتابتها، كل منها
بمهمة محددة وهي:
الوصول إلى النطاق | القراءة | الكتابة |
---|---|---|
نطاق واحد | spreadsheets.values.get |
spreadsheets.values.update |
النطاقات المتعددة | spreadsheets.values.batchGet |
spreadsheets.values.batchUpdate |
إلحاق | spreadsheets.values.append |
بشكلٍ عام، يُستحسن دمج عدة قراءات أو تحديثات مع
batchGet
وbatchUpdate
(على التوالي)، لأنّ ذلك سيتحسّن
والكفاءة.
يمكنك العثور على أمثلة لكل طريقة من هذه الطرق في صفحة الخيارات الأساسية القراءة وأساسية لكتابة نماذج عن الصفحات. للاطّلاع على جميع النماذج، يُرجى الرجوع إلى إلى صفحة النظرة العامة على النماذج.
قراءة
لقراءة قيم البيانات من ورقة بيانات، تحتاج إلى معرف جدول البيانات وA1
تدوين النطاق. تحديد النطاق بدون رقم تعريف ورقة البيانات (A1:B2
)
تعني أن الطلب يتم تنفيذه على الورقة الأولى في جدول البيانات. لمزيد من المعلومات،
للحصول على معلومات حول معرّفات جداول البيانات وترميز A1، يُرجى الاطّلاع على Google Sheets API.
نظرة عامة:
وهناك العديد من مَعلمات طلب البحث الاختيارية التي تتحكّم في تنسيق الناتج:
مَعلمة التنسيق | القيمة الافتراضية |
---|---|
majorDimension |
صفوف |
valueRenderOption |
FORMATTED_VALUE |
dateTimeRenderOption |
SERIAL_NUMBER |
عليك استخدام السمة dateTimeRenderOption
فقط في حال كانت السمة valueRenderOption
ليس FORMATTED_VALUE
.
ليس هناك حد صريح لكمية البيانات التي يتم عرضها. لا تؤدي الأخطاء إلى عرض أي بيانات. يتم حذف الصفوف والأعمدة اللاحقة الفارغة.
يتم توضيح طريقتي الحصول على المفرد والمجمع أدناه. بالنسبة لعينات البيانات الأساسية قراءة العمليات، راجع القراءة الأساسية.
قراءة نطاق واحد
لقراءة نطاق واحد من القيم من جدول بيانات، استخدم
spreadsheets.values.get
الطلب:
برمجة تطبيقات
Java
JavaScript
Node.js
PHP
Python
Ruby
ويتم عرض الرد على هذا الطلب
ValueRange
الخاص بك.
قراءة نطاقات متعددة
لقراءة نطاقات قيم متعددة وغير متصلة من جدول بيانات، استخدم
spreadsheets.values.batchGet
طلب يتيح لك تحديد عدة نطاقات لاستردادها:
برمجة تطبيقات
Java
JavaScript
Node.js
PHP
Python
Ruby
ويتم عرض الرد على هذا الطلب
BatchGetValuesResponse
يحتوي على spreadsheetId
وقائمة
ValueRange
الأخرى.
كتابة
للكتابة في ورقة، تحتاج إلى معرّف جدول البيانات، وهو نطاق الخلايا في A1 التدوين والبيانات التي ترغب في كتابتها ضمن نص الطلب المناسب الخاص بك. لمزيد من المعلومات حول معرّفات جداول البيانات وتدوين A1، راجع نظرة عامة على Google Sheets API.
تتطلب التحديثات إدخالاً صالحًا
مَعلمة ValueInputOption
.
أما بالنسبة إلى التعديلات الفردية، فهي معلمة طلب بحث مطلوبة. بالنسبة إلى التحديثات المجمّعة،
هذه المعلمة مطلوبة في نص الطلب. عناصر التحكّم في "ValueInputOption
"
كيفية تفسير بيانات الإدخال وما إذا كان سيتم تحليل سلاسل الإدخال أو
لا، كما هو موضح في الجدول التالي:
ValueInputOption |
الوصف |
---|---|
RAW |
لا يتم تحليل الإدخال ويتم إدراجه كسلسلة. على سبيل المثال، الإدخال "=1+2" يضع السلسلة، وليس المعادلة، "=1+2" في الخلية. (يتم دائمًا التعامل مع القيم التي ليست سلسلة، مثل القيم المنطقية أو الأرقام على أنّها RAW ). |
USER_ENTERED |
يتم تحليل الإدخال بالضبط كما لو تم إدخاله في واجهة مستخدم "جداول بيانات Google". على سبيل المثال، "1 آذار (مارس) 2016" تصبح تاريخًا، و"=1+2" تصبح معادلة. ويمكن أيضًا استنتاج التنسيقات، وبالتالي "100.15 دولار أمريكي" رقمًا بتنسيق عملة. |
في ما يلي توضيح لطرق التعديل المفرد والمجمّع. بالنسبة لعينات البيانات الأساسية عمليات الكتابة، راجع أساسيات الكتابة.
الكتابة في نطاق واحد
لكتابة البيانات إلى نطاق واحد، استخدم
spreadsheets.values.update
الطلب:
برمجة تطبيقات
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التحديث
ValueRange
، على الرغم من أن الحقل الوحيد المطلوب هو values
. إذا تم تحديد range
، سيتم
مع النطاق في عنوان URL في ValueRange
، يمكنك اختياريًا تحديد
CANNOT TRANSLATE
majorDimension
ويتم استخدام ROWS
تلقائيًا. إذا تم تحديد COLUMNS
، سيتم ضبط قيمة كل صفيف داخلي
كتابتها إلى عمود بدلاً من صف.
وعند تعديلها، يتم تخطّي القيم التي لا تحتوي على بيانات. لمسح البيانات، استخدم حقلاً سلسلة ("").
كتابة نطاقات متعددة
إذا كنت تريد كتابة نطاقات غير متصلة متعددة، فيمكنك استخدام
spreadsheets.values.batchUpdate
الطلب:
برمجة تطبيقات
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التحديث المجمّع
BatchUpdateValuesRequest
الذي يحتوي على ValueInputOption
وقائمة
ValueRange
الكائنات (واحدة لكل نطاق مكتوب). يحدّد كل عنصر ValueRange
خاص به
range
وmajorDimension
وبيانات الإدخال.
إلحاق القيم
لإلحاق بيانات بعد جدول بيانات في ورقة، استخدم
spreadsheets.values.append
الطلب:
برمجة تطبيقات
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التحديث
ValueRange
، على الرغم من أن الحقل الوحيد المطلوب هو values
. إذا تم تحديد range
، سيتم
مع النطاق في عنوان URL في ValueRange
، يمكنك اختياريًا تحديد
CANNOT TRANSLATE
majorDimension
ويتم استخدام ROWS
تلقائيًا. إذا تم تحديد COLUMNS
، سيتم ضبط قيمة كل صفيف داخلي
كتابتها إلى عمود بدلاً من صف.
يتم استخدام نطاق الإدخال للبحث عن البيانات الموجودة والعثور على "جدول" في نطاق
هذا النطاق. يتم إلحاق القيم بالصف التالي من الجدول، بدءًا من
العمود الأول من الجدول. على سبيل المثال، ننصحك باستخدام السمة Sheet1
التي تبدو كما يلي:
A | ب | C | D | E | |
1 | x | y | z | ||
2 | x | y | z | ||
3 | |||||
4 | x | y | |||
5 | y | z | |||
6 | x | y | z | ||
7 |
تتضمّن ورقة البيانات جدولَين: A1:C2
وB4:D6
. القيم الملحقة سوف
تبدأ في B7
لجميع إدخالات range
التالية:
Sheet1
، لأنّها ستفحص جميع البيانات في ورقة البيانات وتحدّد بأن الجدول الموجود فيB4:D6
هو الجدول الأخير.B4
أوC5:D5
، لأنهما كلاهما في جدولB4:D6
.B2:D4
، لأن الجدول الأخير في النطاق هو الجدولB4:D6
(على الرغم من أنّه يحتوي أيضًا على جدولA1:C2
).A3:G10
، لأن الجدول الأخير في النطاق هو الجدولB4:D6
(على الرغم من البدء قبله وانتهائه بعده).
لن تبدأ إدخالات range
التالية في الكتابة في B7
:
- ستبدأ
A1
في الكتابة فيA3
، لأن هذا موجود في جدولA1:C2
. - ستبدأ الكتابة من قِبل
E4
في الكتابة فيE4
، لأنها ليست في أي جدول. (ستبدأ اللغةA4
في الكتابة أيضًا فيA4
للأسباب نفسها).
بالإضافة إلى ذلك، يمكنك اختيار ما إذا كنت تريد استبدال البيانات الحالية بعد
جدول أو إدراج صفوف جديدة للبيانات الجديدة. يستبدل المُدخل البيانات تلقائيًا
بعد الطاولة. لكتابة البيانات الجديدة في صفوف جديدة، استخدم
InsertDataOption
وحدد insertDataOption=INSERT_ROWS
.
لمزيد من المعلومات عن حدود الخلايا الصفوف والصفوف في "جداول بيانات Google"، يُرجى الاطّلاع على الملفات التي يمكنك تخزينها في Google Drive