نظرة عامة على 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 نطاقًا محميًا.