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

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