نظرة عامة على 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 إلى جميع الخلايا في الصفين الأول والثاني من Sheet1.
  • تشير Sheet1!A5:A إلى جميع خلايا العمود الأول من "ورقة بيانات 1"، بدءًا من الصف 5.
  • يشير A1:B2 إلى جميع الخلايا في الصفين والعمودين الأولين من ورقة البيانات الأولى المرئية.
  • تشير Sheet1 إلى جميع الخلايا في Sheet1.
  • يشير 'Jon's_Data'!A1:D5 إلى جميع الخلايا في الصفوف الخمسة الأولى والأعمدة الأربعة الأولى من ورقة بيانات باسم "Jon's_Data".
  • تشير 'My Custom Sheet'!A:A إلى جميع الخلايا في العمود الأول من ورقة باسم "My Custom Sheet".
  • يشير 'My Custom Sheet' إلى جميع الخلايا في "ورقة البيانات المخصّصة".

يجب استخدام علامات اقتباس فردية لأسماء أوراق البيانات التي تتضمّن مسافات أو رموزًا خاصة.

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

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