يمكن أن تحتوي جداول البيانات على أوراق متعددة، تحتوي كل ورقة على أي عدد من الصفوف أو الأعمدة. الخلية هي موقع عند تقاطع صف وعمود معين، وقد تحتوي على قيمة بيانات. وتوفر 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
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
يتم عرض الاستجابة لهذا الطلب على شكل
كائن ValueRange
.
قراءة نطاقات متعددة
لقراءة نطاقات قيم متعددة وغير متواصلة من جدول بيانات، استخدِم طلب spreadsheets.values.batchGet
الذي يتيح لك تحديد نطاقات متعددة لاستردادها:
Apps Script
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
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التعديل كائن ValueRange
، إلا أنّ الحقل الوحيد المطلوب هو values
. إذا تم تحديد range
، يجب
أن يتطابق مع النطاق في عنوان URL. في ValueRange
، يمكنك تحديد
majorDimension
بشكل اختياري.
ويتم استخدام ROWS
تلقائيًا. إذا تم تحديد COLUMNS
، ستتم كتابة كل صفيف داخلي
في عمود بدلاً من صف.
وعند تعديلها، يتم تخطّي القيم التي لا تحتوي على بيانات. لمحو البيانات، استخدم سلسلة فارغة ("").
كتابة نطاقات متعددة
إذا أردت كتابة عدة نطاقات غير متصلة، يمكنك استخدام طلب spreadsheets.values.batchUpdate
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التحديث المجمّع عبارة عن كائن
BatchUpdateValuesRequest
يحتوي على ValueInputOption
وقائمة بكائنات
ValueRange
(واحدة لكل نطاق مكتوب). يحدّد كل عنصر ValueRange
بيانات
range
وmajorDimension
وبيانات الإدخال الخاصة به.
إلحاق القيم
لإلحاق بيانات بعد جدول بيانات في جدول بيانات، يمكنك استخدام طلب spreadsheets.values.append
:
Apps Script
Java
JavaScript
Node.js
PHP
Python
Ruby
يجب أن يكون نص طلب التعديل كائن ValueRange
، إلا أنّ الحقل الوحيد المطلوب هو values
. إذا تم تحديد range
، يجب
أن يتطابق مع النطاق في عنوان URL. في ValueRange
، يمكنك تحديد
majorDimension
بشكل اختياري.
ويتم استخدام ROWS
تلقائيًا. إذا تم تحديد COLUMNS
، ستتم كتابة كل صفيف داخلي
في عمود بدلاً من صف.
يتم استخدام نطاق الإدخال للبحث عن البيانات الموجودة والعثور على "جدول" داخل هذا النطاق. يتم إلحاق القيم بالصف التالي من الجدول، بدءًا من
العمود الأول من الجدول. على سبيل المثال، ننصحك باستخدام السمة Sheet1
التي تبدو كما يلي:
جيم | B | 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 Drive.