نظرة عامة على Google Sheets API (original) (raw)

واجهة برمجة تطبيقات "جداول بيانات Google" هي واجهة RESTful تتيح لك قراءة بيانات جدول بيانات وتعديلها. تتيح لك واجهة برمجة التطبيقات Sheets API تنفيذ ما يلي:

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

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

جدول بيانات

العنصر الأساسي في "جداول بيانات Google". ويمكن أن يحتوي على عدّة Sheets، يتضمن كل منها معلومات منظَّمة في Cells. يمثّل الموردspreadsheetsجدول بيانات. أن تحتوي على قيمة spreadsheetIdفريدة

رقم تعريف جدول البيانات

المعرّف الفريد لجدول بيانات وهو عبارة عن سلسلة معيّنة تحتوي على أحرف وأرقام وبعض الرموز الخاصة التي تشير إلى جدول بيانات، ويمكن اشتقاقه من عنوان URL الخاص بجدول البيانات. تكون أرقام تعريف جدول البيانات ثابتة، حتى في حال تغيير اسم جدول البيانات.

https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit?gid=SHEET_ID#gid=SHEET_ID

الجدول

صفحة أو علامة تبويب ضمن جدول بيانات يمثّل الموردSheetsورقة بيانات. يحتوي على قيمة عددية فريدة sheetId وورقة بياناتtitle كجزء من العنصرSheetProperties.

رقم تعريف ورقة البيانات

المعرّف الفريد لصفحة معيّنة ضمن جدول بيانات وهو عدد كلي معيّن يحتوي على أرقام تشير إلى ورقة بيانات ويمكن أن يتم تحديده من عنوان URL لجدول البيانات. تكون أرقام تعريف الأوراق ثابتة، حتى إذا تغيّر اسم الورقة. للحصول على مثال، اطّلِع على معرّف جدول البيانات.

الخلية

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

ترميز 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 إلى جميع الخلايا في الصفوف الخمسة الأولى والأعمدة الأربعة من ورقة بيانات باسم "بيانات_جون".
• تشير 'My Custom Sheet'!A:A إلى جميع الخلايا في أول عمود من ورقة بيانات باسم "My Custom Sheet".
• تشير 'My Custom Sheet' إلى جميع الخلايا في "جدولي المخصّص".

يجب استخدام علامات الاقتباس المفردة لأسماء الأوراق التي تحتوي على مسافات أو رموز خاصة.

ملاحظة: استخدِم أسماء مختلفة للعناصر في جداول البيانات كلما أمكن ذلك. على سبيل المثال، تشير A1 (بدون علامات اقتباس) إلى الخلية A1 في أول ورقة مرئية. يشير 'A1' إلى ورقة بيانات تحمل الاسم A1. وبالمثل، تشير ورقة البيانات1 إلى ورقة بيانات تحمل الاسم "ورقة البيانات1". ومع ذلك، إذا كان هناك نطاق مُعنوَن بعنوان "الورقة1"، تشير "الورقة1" إلى النطاق المُعنوَن ويشير 'Sheet1' إلى الورقة.

ترميز R1C1

بنية نحوية تُستخدَم لتحديد خلية أو نطاق خلايا باستخدام سلسلة تحتوي على اسم الورقة بالإضافة إلى إحداثيات الخلية الأولى والخلية الأخيرة باستخدام أرقام الصفوف والأعمدة هذه الطريقة أقل شيوعًا من أسلوب A1، ولكن يمكن أن تكون مفيدة عند الإشارة إلى نطاق خلايا نسبةً إلى موضع خلية معيّن.

عرض الأمثلة

• تشير Sheet1!R1C1:R2C2 إلى أول خليتين في الصفين العلويين من ورقة البيانات "الورقة1".
• يشير R1C1:R2C2 إلى أول خليتين في أعلى صفين من أول ورقة مرئية.
• يشير Sheet1!R[3]C[1] إلى الخلية التي تقع ثلاثة صفوف أسفل الخلية الحالية وعمود واحد على يمينها.

النطاق المُعنوَن

خلية محدّدة أو نطاق من الخلايا يحمل اسمًا مخصّصًا لتبسيط المرجعات في جميع أنحاء التطبيق يمثّل الموردFilterViewنطاقًا مُعنوَنًا.

النطاق المحمي

خلية محدّدة أو نطاق من الخلايا لا يمكن تعديله يمثّل ملف مواردProtectedRangeنطاقًا محميًا.

• للتعرّف على كيفية التطوير باستخدام واجهات برمجة تطبيقات Google Workspace، بما في ذلك التعامل مع مصادقة وتفويض، يُرجى الاطّلاع على مقالة التطوير على Google Workspace.
• للتعرّف على كيفية ضبط تطبيق Sheets API وتشغيله، جرِّب الدليل السريع لبدء استخدام JavaScript.

إنّ محتوى هذه الصفحة مرخّص بموجب ترخيص Creative Commons Attribution 4.0‏ ما لم يُنصّ على خلاف ذلك، ونماذج الرموز مرخّصة بموجب ترخيص Apache 2.0‏. للاطّلاع على التفاصيل، يُرجى مراجعة سياسات موقع Google Developers‏. إنّ Java هي علامة تجارية مسجَّلة لشركة Oracle و/أو شركائها التابعين.

تاريخ التعديل الأخير: 2025-05-08 (حسب التوقيت العالمي المتفَّق عليه)