كيف تربط Google Sheets بتطبيقك

لربط Google Sheets بتطبيقك، فعّل Google Sheets API في مشروع Google Cloud، وأنشئ حساب خدمة (service account)، وشارك الجدول مع بريد حساب الخدمة الإلكتروني، واحفظ مفتاحه كـسر من جانب الخادم. ثم يقرأ خادمك الصفوف بـ spreadsheets.values.get ويضيف صفوفًا بـ spreadsheets.values.append. وإذا احتاج المستخدمون إلى ربط جداولهم الخاصة، فاستخدم OAuth بدلًا من ذلك. وإذا كان الجدول عامًا بالكامل، فمفتاح API بسيط يكفي للقراءة.

يغطي هذا الدليل الطريقة المناسبة، والاستدعاءات التي تحتاجها، والحصص والمزالق، وموجّهات لمنشئ التطبيقات بالذكاء الاصطناعي. وتفاصيل Google مستمدة من وثائق المطورين لدى Google حتى سبتمبر 2026.

لماذا تربط جدولًا أصلًا

أسباب شائعة:

• الحفاظ على سير عمل الفريق. يستمر الموظفون في تحرير قائمة أسعار أو جدول في Sheets، ويعرضه التطبيق.
• جمع البيانات في المكان الذي ينظر إليه الناس أصلًا. تظهر التسجيلات الجديدة أو الطلبات أو ردود النماذج كصفوف.
• التقارير. تصدير بيانات التطبيق إلى جدول لمن يعملون بالجداول يوميًا.
• خطوة انتقالية. ابدأ من الجدول، ثم انتقل إلى قاعدة بيانات مناسبة. راجع كيف تحوّل جدول بيانات إلى تطبيق.

اختر طريقة تسجيل تطبيقك في Google

تصف إرشادات بيانات الاعتماد لدى Google ثلاثة أنواع:

لمعظم التطبيقات، حساب الخدمة هو الخيار الصحيح: مجموعة واحدة من بيانات الاعتماد تملكها أنت، ولا تصل إلا إلى الجداول التي تشاركها معه صراحةً.

خطوة بخطوة مع حساب خدمة

1. أنشئ مشروع Google Cloud أو اختر مشروعًا قائمًا وفعّل Google Sheets API.
2. أنشئ حساب خدمة ومفتاحًا له. المفتاح ملف JSON، عامله معاملة كلمة المرور.
3. شارك الجدول مع بريد حساب الخدمة، كمشاهد للقراءة فقط أو كمحرر للكتابة. تقول إرشادات Google إن ذلك يتم عبر شاشة المشاركة المعتادة.
4. احفظ المفتاح كسر على خادمك، مثل GOOGLE_SERVICE_ACCOUNT_JSON، مع معرّف الجدول (السلسلة الطويلة في رابط الجدول) باسم SHEET_ID.
5. استدعِ الواجهة من الخادم باستخدام مكتبة Google العميلة للغتك.
6. خزّن القراءات مؤقتًا إذا كان كثيرون يرون البيانات نفسها، حتى لا تصطدم بالحصة.

الاستدعاءات التي ستستخدمها

من دليل Google لقراءة القيم وكتابتها:

تستخدم النطاقات تدوين A1. وتنبه Google إلى أن النطاق دون اسم ورقة، مثل A1:B2، يُطبّق على الورقة الأولى، لذا سمِّ التبويب صراحةً لتجنب المفاجآت عندما يعيد أحدهم ترتيب التبويبات.

RAW مقابل USER_ENTERED

تحتاج عمليات الكتابة إلى valueInputOption:

• RAW يخزّن بالضبط ما ترسله، كنص. فالقيمة =1+2 تُخزَّن كنص =1+2.
• USER_ENTERED يعامل المدخل كأنه كُتب في Sheets: فالتواريخ تصبح تواريخ، و=1+2 تصبح صيغة.

إذا كنت تكتب نصًا كتبه المستخدمون في تطبيقك، فاستخدم RAW. ومع USER_ENTERED قد يرسل أحدهم صيغة تُنفَّذ عندما يفتح زميل الجدول.

الحصص والأخطاء

اعتبارًا من سبتمبر 2026، تسرد صفحة حدود Sheets API لدى Google التالي:

لا يوجد حد يومي ما دمت ضمن حصص الدقيقة. وتجاوزها يعيد 429: Too many requests، وتوصي Google بـالتراجع الأُسّي المقتطع: انتظر مدة أطول بعد كل محاولة فاشلة، مع تأخير عشوائي، حتى حد أقصى. ويفشل الطلب الواحد الذي يستغرق أكثر من 180 ثانية بسبب المهلة الزمنية.

عمليًا: لا تستدعِ الواجهة في كل عرض صفحة. خزّن بيانات الجدول مؤقتًا لدقيقة أو أكثر، ودمج القراءات بـ batchGet، ودمج عمليات الكتابة حيثما أمكن.

الخيارات والمفاضلات

لأي شيء يخص مستخدمين كثيرين أو بيانات حساسة، تكون قاعدة البيانات مصدر الحقيقة الأفضل. راجع ما هي قاعدة البيانات.

موجّهات لمنشئ التطبيقات بالذكاء الاصطناعي

لقراءة جدول:

اعرض تبويب «Menu» من جدولنا في Google Sheets على صفحة القائمة. استخدم Google Sheets API من الخادم مع حساب خدمة يوجد مفتاح JSON الخاص به في السر GOOGLE_SERVICE_ACCOUNT_JSON، ومعرّف الجدول في SHEET_ID. اقرأ النطاق Menu!A2:D (الاسم، والوصف، والسعر، والفئة). خزّن النتيجة مؤقتًا لمدة 5 دقائق. إذا فشلت الواجهة، اعرض آخر نسخة محفوظة. لا ترسل المفتاح أبدًا إلى المتصفح.

لكتابة الصفوف:

عندما يرسل أحدهم نموذج التواصل، احفظه في قاعدة بياناتنا، وأضف أيضًا صفًا إلى تبويب «Leads» (التاريخ، والاسم، والبريد، والرسالة) باستخدام spreadsheets.values.append مع valueInputOption بقيمة RAW. إذا أعادت Google الخطأ 429، فأعد المحاولة بالتراجع الأُسّي؛ وإذا فشل ذلك أيضًا، فأبقِ العميل المحتمل في قاعدة البيانات وأعد المحاولة لاحقًا.

أخطاء شائعة

• نسيان مشاركة الجدول مع بريد حساب الخدمة. فتعيد الواجهة خطأ صلاحيات رغم أن المفتاح سليم.
• المفتاح في الواجهة الأمامية أو في المستودع. يمنح ملف JSON للمفتاح الوصول إلى كل جدول مشترك معه. راجع كيف تحافظ على أمان مفاتيح API.
• استخدام USER_ENTERED لمدخلات المستخدمين، وهذا يسمح بحقن الصيغ.
• استدعاء الواجهة مع كل طلب والوصول إلى حد الدقيقة عند أول ذروة في الزيارات.
• الاعتماد على مواضع الأعمدة. يُدرج أحدهم عمودًا فيقرأ التطبيق بيانات خاطئة. اقرأ صف العناوين وطابق بالاسم، أو ثبّت الترويسة.
• مشاركة الجدول أوسع مما يلزم. فخيار «أي شخص لديه الرابط» يجعله عامًا.
• استخدام الجدول كقاعدة بيانات متعددة المستخدمين. فالكتابات المتزامنة والصلاحيات الناقصة تسببان ضياع البيانات أو تسريبها.

قائمة تحقق

• تم تفعيل Sheets API وإنشاء حساب الخدمة
• الجدول مشترك مع بريد حساب الخدمة بأدنى دور مطلوب
• المفتاح ومعرّف الجدول محفوظان كأسرار على الخادم
• كل الاستدعاءات تتم من الخادم
• أسماء التبويبات مستخدمة في النطاقات
• تُستخدم RAW لنصوص المستخدمين
• القراءات مخزّنة مؤقتًا، ويُعالج الخطأ 429 بالتراجع
• يستمر التطبيق بسلاسة إذا لم تكن Sheets متاحة
• تم تحديد أي طرف هو مصدر الحقيقة

Google Sheets في Mythex

لدى Mythex طريقتان مختلفتان للعمل مع Sheets. الموصلات (Connectors) تربط حساب Google الخاص بك بـ Mythex حتى يستطيع الوكيل استخدامه أثناء البناء، مثل قراءة جدول لبناء لوحة معلومات منه؛ وتقول الوثائق إن بيانات الاعتماد تبقى لدى خدمة الاتصال في Mythex ولا تصل إلى كودك أبدًا (راجع الموصلات، ووافق على كل صلاحية تطلبها Google). أما لكي يقرأ التطبيق المنشور الجدول أو يكتب فيه بمفرده، فالطريقة الموثوقة هي التي في هذا الدليل: مفتاح حساب خدمة محفوظ كسر للمشروع، واستدعاءات Sheets API من خادمك، كما في دمج أي واجهة API. وإذا تجاوزت الجدول، فاطلب من الوكيل نقل البيانات إلى قاعدة بيانات المشروع، وبناء لوحة معلومات فوقها.

الأسئلة