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

Google Sheets API هي واجهة مريحة تتيح لك قراءة بيانات جدول البيانات وتعديلها. وتشمل الاستخدامات الأكثر شيوعًا لواجهة برمجة التطبيقات هذه المهام التالية:

  • إنشاء جداول بيانات
  • قراءة وكتابة قيم خلايا جدول البيانات
  • تعديل تنسيق جدول البيانات
  • إدارة "أوراق البيانات المرتبطة"

في ما يلي قائمة بالمصطلحات الشائعة المستخدمة في Sheets API:

جدول البيانات

الكائن الأساسي في Google Sheets الذي يمكن أن يحتوي على أوراق متعددة، لكل منها معلومات منظمة مضمنة في الخلايا. يمثل مورد جدول البيانات كل جدول بيانات ويكون له قيمة spreadsheetId فريدة تحتوي على أحرف أو أرقام أو واصلات أو شُرَط سفلية. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجدول البيانات على جداول بيانات Google:

https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0

جدول بيانات

صفحة أو علامة تبويب ضمن جدول بيانات. يمثل مورد الورقة كل ورقة وله عنوان فريد وقيمة sheetId رقمية. يمكنك العثور على معرف الورقة في عنوان URL لجدول بيانات Google:

https://docs.google.com/spreadsheets/d/aBC-123_xYz/edit#gid=sheetId

خلية

حقل فردي من النص أو البيانات داخل ورقة. يتم ترتيب الخلايا في صفوف وأعمدة ويمكن تجميعها كنطاق من الخلايا. يمثل مورد CellData كل خلية، ولكن ليس لها قيمة معرّف فريدة. بدلاً من ذلك، تحدد إحداثيات الصف والعمود الخلايا.

الترميز A1

بناء جملة يستخدم لتعريف خلية أو نطاق من الخلايا بسلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات خلية البداية والنهاية باستخدام أحرف الأعمدة وأرقام الصفوف. هذه الطريقة هي الأكثر شيوعًا وفائدة عند الإشارة إلى نطاق مطلق من الخلايا.

عرض الأمثلة

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

الخطوات التالية

  • للاطّلاع على معلومات عن التطوير باستخدام واجهات برمجة التطبيقات في Google Workspace، بما في ذلك التعامل مع المصادقة والتفويض، راجِع المقالة التطوير على Google Workspace.

  • لمعرفة كيفية ضبط وتشغيل تطبيق بسيط لواجهة برمجة تطبيقات جداول البيانات، يمكنك الاطّلاع على نظرة عامة على البدء السريع.