نظرة عامة على 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. وبالمثل، تشير ورقة بيانات1 إلى ورقة بيانات تحمل الاسم ورقة بيانات1. ومع ذلك، إذا كان هناك نطاق مُعنوَن بعنوان "Sheet1"، يشير Sheet1 إلى النطاق المُعنوَن وتشير 'Sheet1' إلى ورقة البيانات.

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