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

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

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

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

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

الكائن الأساسي في "جداول بيانات Google" الذي يمكن أن يحتوي على أوراق متعددة، لكل منها معلومات منظمة مضمنة في الخلايا. يمثل مورد جدول البيانات كل جدول بيانات وله قيمة 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.

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