يمكن أن تحتوي جداول البيانات على أوراق متعددة، وتحتوي كل ورقة على أي عدد من الصفوف أو الأعمدة. الخلية هي موقع عند تقاطع
صف وعمود معين، وقد تحتوي على قيمة بيانات. توفر واجهة برمجة تطبيقات Google Sheets المورد 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
، يمكنك تحديد
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
، يمكنك تحديد
majorDimension
بشكل اختياري.
ويتم استخدام "ROWS
" تلقائيًا. إذا تم تحديد COLUMNS
، تتم كتابة كل صفيف داخلي
إلى عمود بدلاً من صف.
يُستخدم نطاق الإدخال للبحث عن البيانات الحالية والعثور على "جدول" ضمن هذا النطاق. يتم إلحاق القيم بالصف التالي من الجدول، بدءًا من العمود الأول في الجدول. على سبيل المثال، ضع في الاعتبار Sheet1
الذي يبدو كما يلي:
A | 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"، راجِع الملفات التي يمكنك تخزينها في Google Drive.