نظرة عامة على Google Sheets API

‫Google Sheets API هي واجهة RESTful تتيح لك قراءة بيانات جدول بيانات وتعديلها. تتيح لك واجهة برمجة التطبيقات Sheets API تنفيذ ما يلي:

  • إنشاء جداول بيانات
  • قراءة قيم خلايا جدول البيانات وكتابتها
  • تعديل تنسيق جدول البيانات
  • إدارة "أوراق البيانات المرتبطة"

في ما يلي قائمة بالمصطلحات الشائعة المستخدَمة في Sheets API:

جدول بيانات

العنصر الأساسي في "جداول بيانات Google". ويمكن أن يحتوي على عدّة Sheets، يتضمن كل منها معلومات منظَّمة في Cells. يمثّل المورد spreadsheets جدول بيانات. يحتوي على قيمة spreadsheetId فريدة.

رقم تعريف جدول البيانات
المعرّف الفريد لجدول بيانات وهو عبارة عن سلسلة معيّنة تحتوي على أحرف وأرقام وبعض الرموز الخاصة التي تشير إلى جدول بيانات، ويمكن اشتقاقه من عنوان URL الخاص بجدول البيانات. تكون أرقام تعريف جدول البيانات ثابتة، حتى إذا تغيّر اسم جدول البيانات.
https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?gid=SHEET_ID#gid=SHEET_ID
الجدول

صفحة أو علامة تبويب ضمن جدول بيانات يمثّل المورد Sheets ورقة بيانات. يحتوي على قيمة عددية فريدة sheetId وورقة بيانات title كجزء من العنصر SheetProperties.

رقم تعريف ورقة البيانات
المعرّف الفريد لصفحة معيّنة ضمن جدول بيانات وهي سلسلة معيّنة تحتوي على أحرف وأرقام وبعض الأحرف الخاصة تشير إلى ورقة بيانات ويمكن الحصول عليها من عنوان URL لجدول البيانات. تكون أرقام تعريف الأوراق ثابتة، حتى إذا تغيّر اسم الورقة. للحصول على مثال، يُرجى الاطّلاع على معرّف جدول البيانات.
الخلية

حقل فردي للنص أو البيانات داخل ورقة بيانات يتم ترتيب الخلايا في صفوف وأعمدة، ويمكن تجميعها كنطاق من الخلايا. يمثّل المورد Cells كل خلية، ولكنّه لا يحتوي على قيمة رقم تعريف فريد. بدلاً من ذلك، تحدِّد إحداثيات الصف والعمود الخلايا.

ترميز A1
بنية نحوية تُستخدَم لتحديد خلية أو نطاق خلايا باستخدام سلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات الخلية الأولى والخلية الأخيرة باستخدام أحرف الأعمدة وأرقام الصفوف هذه الطريقة هي الأكثر شيوعًا وفائدة عند الإشارة إلى نطاق مطلق من الخلايا.

عرض الأمثلة

  • تشير Sheet1!A1:B2 إلى جميع الخلايا في الصفين والعمودَين الأولَين من ورقة البيانات Sheet1.
  • تشير Sheet1!A:A إلى جميع الخلايا في العمود الأول من ورقة البيانات Sheet1.
  • تشير Sheet1!1:2 إلى جميع الخلايا في الصفين الأولين من ورقة البيانات "الورقة1".
  • تشير Sheet1!A5:A إلى جميع خلايا العمود الأول في "الصفحة 1"، بدءًا من الصف 5 فصاعدًا.
  • يشير A1:B2 إلى جميع الخلايا في الصفين والعمودَين الأولَين من أول ورقة بيانات مرئية.
  • تشير Sheet1 إلى جميع الخلايا في ورقة البيانات Sheet1.
  • يشير 'Jon's_Data'!A1:D5 إلى جميع الخلايا في الصفوف الخمسة الأولى والأعمدة الأربعة من ورقة بيانات باسم "بيانات_جون".
  • تشير 'My Custom Sheet'!A:A إلى جميع الخلايا في أول عمود من ورقة بيانات باسم "My Custom Sheet".
  • تشير 'My Custom Sheet' إلى جميع الخلايا في "جدولي المخصّص".

يجب استخدام علامتَي اقتباس مفردتَين لأسماء الأوراق التي تحتوي على مسافات أو رموز خاصة أو مجموعة أبجدية رقمية.

ملاحظة: استخدِم أسماء مختلفة للعناصر في جداول البيانات كلما أمكن ذلك. على سبيل المثال، تشير A1 (بدون علامات اقتباس) إلى الخلية A1 في أول ورقة مرئية. تشير 'A1' إلى ورقة بيانات باسم A1. وبالمثل، تشير ورقة البيانات 1 إلى ورقة بيانات تحمل الاسم "ورقة البيانات 1". ومع ذلك، إذا كان هناك نطاق مُعنوَن بعنوان "الورقة1"، تشير "الورقة1" إلى النطاق المُعنوَن ويشير 'Sheet1' إلى الورقة.
ترميز R1C1
بنية نحوية تُستخدَم لتحديد خلية أو نطاق خلايا باستخدام سلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات الخلية الأولى والخلية الأخيرة باستخدام أرقام الصفوف والأعمدة هذه الطريقة أقل شيوعًا من أسلوب A1، ولكن يمكن أن تكون مفيدة عند الإشارة إلى نطاق خلايا نسبةً إلى موضع خلية معيّن.

عرض الأمثلة

  • تشير Sheet1!R1C1:R2C2 إلى أول خليتين في الصفين العلويين من ورقة البيانات "الورقة1".
  • يشير R1C1:R2C2 إلى أول خليتين في الصفين العلويين من أول ورقة مرئية.
  • يشير الرمز Sheet1!R[3]C[1] إلى الخلية التي تقع ثلاثة صفوف أسفل الخلية الحالية وعمود واحد على يمينها.
النطاق المُعنوَن
خلية محدّدة أو نطاق من الخلايا يحمل اسمًا مخصّصًا لتبسيط الإحالات في جميع أنحاء التطبيق يمثّل المورد FilterView نطاقًا مُعنوَنًا.
النطاق المحمي
خلية محدّدة أو نطاق من الخلايا لا يمكن تعديله يمثّل ملف موارد ProtectedRange نطاقًا محميًا.