واجهة برمجة تطبيقات Google Sheets هي واجهة مريحة تتيح لك قراءة بيانات جدول البيانات وتعديلها. تشمل الاستخدامات الأكثر شيوعًا لواجهة برمجة التطبيقات المهام التالية:
- إنشاء جداول البيانات
- قراءة وكتابة قيم خلايا جدول البيانات
- تعديل تنسيق جدول البيانات
- إدارة "أوراق البيانات المرتبطة"
في ما يلي قائمة بالمصطلحات الشائعة المستخدمة في 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.
لمعرفة كيفية إعداد وتشغيل تطبيق بسيط من Sheets API، يمكنك الاطّلاع على نظرة عامة على البدء السريع.