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