Google Sheets API هي واجهة REST تتيح لك قراءة بيانات جدول البيانات وتعديلها. تتضمن الاستخدامات الأكثر شيوعًا لواجهة برمجة التطبيقات هذه المهام التالية:
- إنشاء جداول بيانات
- قراءة قيم خلايا جدول البيانات وكتابتها
- تعديل تنسيق جدول البيانات
- إدارة أوراق البيانات المرتبطة
في ما يلي قائمة بالمصطلحات الشائعة المستخدمة في Sheets API:
- جدول بيانات
هو الكائن الأساسي في جداول بيانات Google الذي يمكن أن يحتوي على أوراق متعددة، تحتوي كل منها على معلومات منظمة مضمنة في الخلايا. يمثّل مورد جدول البيانات كل جدول بيانات وله قيمة فريدة للسمة
spreadsheetIdتحتوي على أحرف أو أرقام أو واصلات أو شرطات سفلية. يمكنك العثور على رقم تعريف جدول البيانات في عنوان URL لجداول بيانات Google:https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0- جدول بيانات Google
صفحة أو علامة تبويب داخل جدول بيانات. يمثِّل مورد الورقة كل ورقة بيانات ولها عنوان فريد وقيمة
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'إلى جميع الخلايا في "جدول البيانات المخصّص".
نصيحة: استخدِم أسماء مختلفة للكائنات داخل جداول البيانات، حيثما أمكن. على سبيل المثال، تشير 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 بسيطًا، اطّلِع على نظرة عامة حول الخطوات السريعة.