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

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

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

في ما يلي قائمة بالمصطلحات الشائعة المستخدمة في واجهة برمجة التطبيقات هذه:

جدول بيانات

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

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

جدول بيانات Google

صفحة أو علامة تبويب داخل جدول بيانات. Sheet المورد كل لها عنوان فريد ورقمي sheetId إِنْتَ يمكنك العثور على معرف الورقة في عنوان URL لـ Google Sheets:

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.
  • تشير 'Jon's_Data'!A1:D5 إلى جميع الخلايا في الصفوف الخمسة الأولى وأربعة أعمدة في ورقة باسم "Jon's_Data".
  • تشير '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، يمكنك الاطّلاع على نظرة عامة حول البدايات السريعة.