كيفية إنشاء نموذج ملاحظات باستخدام Google Sheets API وNext.js

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

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

ما الذي ستتعلمه في هذا المقال؟

• إعداد مشروع جديد داخل Google Cloud Console.
• تفعيل Google Sheets API وربطه بجدول بيانات.
• إنشاء نموذج Front-end باستخدام Next.js.
• إرسال البيانات من النموذج إلى Google Sheets عبر API Routes.
• ضبط متغيرات البيئة والتعامل مع بيانات الاعتماد بشكل صحيح.

إعداد مشروع جديد في Google Cloud Console

للوصول إلى Google Sheets API، يجب أولًا إنشاء مشروع جديد داخل Google Cloud Console. بعد الدخول إلى المنصة، أنشئ مشروعًا جديدًا باسم مناسب لطبيعة التطبيق.

بعد إنشاء المشروع، انتقل إلى قسم APIs and Services ثم اختر Enable APIs and Services.

ابحث عن Google Sheets API من المكتبة ثم قم بتفعيله.

إنشاء Service Account

بعد تفعيل الواجهة البرمجية، انتقل إلى Credentials ثم اختر New Credential وأنشئ Service Account جديدًا.

أدخل اسمًا مناسبًا للحساب، ثم أكمل بقية البيانات. بعد الإنشاء، احتفظ بعنوان البريد الإلكتروني الخاص بـ Service Account لأننا سنستخدمه لاحقًا لمنح صلاحية الوصول إلى ملف Google Sheets.

يمكنك اعتبار هذا الحساب بمثابة كيان آلي Bot Account يتولى تنفيذ الطلبات القادمة من التطبيق.

إنشاء مفتاح بصيغة JSON

الآن افتح Service Account الذي أنشأته، ثم توجه إلى قسم Keys واضغط على Add Key. احرص على اختيار التنسيق JSON.

سيتم تنزيل ملف يحتوي على بيانات الاعتماد اللازمة للتواصل بين تطبيقك وGoogle Sheets API. هذا الملف مهم جدًا، ويجب التعامل معه بسرية تامة وعدم رفعه إلى مستودع GitHub.

ربط المشروع بجدول Google Sheets

بعد تجهيز المشروع في Google Cloud، انتقل إلى Google Sheets وأنشئ ملف Spreadsheet جديدًا. يمكنك إضافة بعض البيانات التجريبية إذا رغبت، حتى تختبر القراءة أو الكتابة لاحقًا بسهولة.

بعد ذلك، اضغط على Share وأضف البريد الإلكتروني الخاص بـ Service Account الذي أنشأته سابقًا، ثم امنحه صلاحية Editor. ومن الأفضل إلغاء خيار إشعار المستخدمين.

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

إنشاء الواجهة الأمامية باستخدام Next.js

في هذا الشرح سنستخدم Next.js لبناء الواجهة الأمامية للنموذج، وسنعتمد على API Routes لإرسال طلب POST إلى Google Sheets.

ابدأ بإنشاء مشروع جديد عبر الأمر التالي:

npx create-next-app

ولتبسيط عملية بناء النموذج وتحسين تجربة التطوير، ثبّت الحزم التالية:

npm i @chakra-ui/react @emotion/react@^11 @emotion/styled@^11 framer-motion@^4 react-hook-form

لماذا هذه الحزم؟

• Chakra-UI: مكتبة واجهات تساعد على بناء عناصر UI بشكل سريع ومرن.
• react-hook-form: مكتبة فعالة لإدارة النماذج والتعامل مع القيم والتحقق من المدخلات.
• framer-motion و @emotion: مطلوبة لدعم Chakra-UI وتشغيلها بسلاسة.

في Next.js، كل ملف داخل مجلد /pages يمثل مسارًا مستقلًا. ويمكنك استخدام الملف /pages/index.js كنقطة انطلاق لإنشاء النموذج الرئيسي.

بناء الهيكل الأولي للنموذج

import { VStack, Text, Input } from "@chakra-ui/react"

function Home ( ) {
  function submitHandler ( ) {
    // POST request
  }

  return (
    <VStack>
      <Text fontSize="2xl" fontWeight="bold">
        Your response matters!
      </Text>

      <form onSubmit={submitHandler}>
        <Input placeholder="Enter Name" />
        <Button>Submit!</Button>
      </form>
    </VStack>
  )
}

المكوّن VStack في Chakra-UI يرتّب العناصر عموديًا، وهو اختصار مفيد لتنسيق مشابه لـ flex-direction: column. ويمكنك بالطبع إضافة حقول أخرى مثل البريد الإلكتروني أو الرسالة أو التقييم حسب الحاجة.

التعامل مع بيانات النموذج باستخدام react-hook-form

لجمع القيم المُدخلة من المستخدمين بشكل منظم، سنستخدم useForm من مكتبة react-hook-form.

import { useForm } from 'react-hook-form';

ثم نفكك القيم المطلوبة من الـ Hook:

const { register, handleSubmit } = useForm();

بعدها نربط النموذج بالدالة handleSubmit:

<form onSubmit={handleSubmit(submitHandler)}>
  { /* Input fields here */ }
</form>

والآن نضيف register إلى حقول الإدخال:

<Input placeholder="Enter your message" {...register('name')} />

ولتجربة القيم المُرسلة في البداية، يمكنك طباعة البيانات داخل وحدة التحكم:

function submitHandler ( data ) {
  console.log(data);
}

هذه الخطوة مفيدة للتأكد من أن النموذج يعمل كما ينبغي قبل ربطه بالواجهة الخلفية.

إنشاء API Route لإرسال البيانات

الخطوة التالية هي إنشاء مسار API داخل Next.js لمعالجة طلبات الإرسال القادمة من النموذج. أنشئ ملفًا جديدًا داخل المسار ./pages/api/ وليكن:

./pages/api/sheet.js

ابدأ باختبار بسيط للتأكد من أن المسار يعمل:

function handler ( req, res ) {
  res.json({ message: "It works!" });
}

export default handler;

يمكنك اختبار ذلك بزيارة الرابط:

http://localhost:3000/api/sheet

إرسال طلب POST من الواجهة الأمامية

بعد التأكد من عمل المسار، حدّث دالة الإرسال في النموذج لتستخدم Fetch API:

async function submitHandler ( data ) {
  const response = await fetch("/api/sheet", {
    method: "POST",
    body: JSON.stringify(data),
    headers: {
      'Content-Type': 'application/json',
    },
  })
}

تثبيت googleapis وربطها مع Google Sheets API

الآن نحتاج إلى مكتبة googleapis حتى يتمكن Next.js من التواصل مع خدمات Google:

npm install googleapis

ثم داخل ملف /pages/api/sheet.js أضف الاستيراد التالي، وتعامل مع البيانات المرسلة من الواجهة:

import { google } from "googleapis"

async function handler ( req, res ) {
  if (req.method === "POST") {
    const { name, message } = req.body;
    res.json({ message: "It works!" });
  }
}

export default handler;

لاحظ أن API Routes تستقبل طلبات GET افتراضيًا، لذلك يجب التحقق صراحة من أن نوع الطلب هو POST.

إعداد متغيرات البيئة

افتح ملف JSON الذي يحتوي على بيانات الاعتماد، ثم أنشئ ملفًا جديدًا باسم .env.local في جذر المشروع، وأضف القيم التالية:

CLIENT_EMAIL=yourclientemail
CLIENT_ID=yourclientid
PRIVATE_KEY=yourprivatekey
SPREADSHEET_ID=yourspreadsheetid

احرص على عدم مشاركة هذا الملف علنًا، وأضفه إلى .gitignore لحماية المفاتيح الحساسة.

إنشاء التوثيق Authentication مع Google

بعد ضبط متغيرات البيئة، نُنشئ كائن المصادقة الذي يسمح للتطبيق بالوصول إلى Google Sheets:

const auth = new google.auth.GoogleAuth({
  credentials: {
    client_email: process.env.CLIENT_EMAIL,
    client_id: process.env.CLIENT_ID,
    private_key: process.env.PRIVATE_KEY.replace(/\\n/g, '\n'),
  },
  scopes: [
    'https://www.googleapis.com/auth/drive',
    'https://www.googleapis.com/auth/drive.file',
    'https://www.googleapis.com/auth/spreadsheets',
  ],
});

تمثل scopes الصلاحيات التي يحتاجها التطبيق، مثل القراءة والكتابة داخل جداول البيانات.

أما استخدام replace(/\\n/g, '\n') في PRIVATE_KEY فهو حل عملي لمشكلة شائعة تتعلق بتنسيق المفتاح داخل متغيرات البيئة، إذ يتم استبدال فواصل الأسطر النصية لتصبح قابلة للقراءة بشكل صحيح.

تهيئة خدمة Google Sheets

const sheets = google.sheets({
  auth,
  version: 'v4',
});

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

إضافة البيانات إلى Google Sheets

الآن نستخدم الدالة spreadsheets.values.append لإضافة بيانات المستخدم إلى الجدول:

const response = await sheets.spreadsheets.values.append({
  spreadsheetId: process.env.DATABASE_ID,
  range: 'Sheet1!A2:C',
  valueInputOption: 'USER_ENTERED',
  requestBody: {
    values: [[name, message]],
  },
});

شرح أهم الخصائص

• spreadsheetId: معرّف ملف Google Sheets، ويمكن الحصول عليه من رابط الجدول.
• range: النطاق الذي ستُكتب فيه البيانات، مثل الأعمدة والصفوف المستهدفة.
• valueInputOption: يحدد كيفية تفسير القيم المدخلة، مثل الأرقام أو النصوص.
• requestBody.values: البيانات الفعلية التي سيتم إدراجها داخل الجدول.

يمكنك العثور على Spreadsheet ID من رابط الجدول بالشكل التالي:

https://docs.google.com/spreadsheets/d/{spreadsheetID}/edit#gid=0

أما إذا كنت غير متأكد من قيمة range المناسبة، فيمكنك تحديدها بصريًا من داخل واجهة Google Sheets.

إذا أردت إضافة أكثر من قيمة في السطر الواحد، يكفي وضعها داخل مصفوفة كما في المثال السابق، مثل name وmessage.

إرجاع استجابة إلى الواجهة الأمامية

بعد اكتمال عملية الإضافة، أرسل استجابة واضحة إلى الواجهة الأمامية:

res.status(201).json({
  response,
  result: "Feedback posted to spreadsheet!"
})

إذا تم كل شيء بشكل صحيح، فسيؤدي إرسال النموذج إلى إضافة صف جديد داخل Google Sheets بنجاح.

متى يكون Google Sheets API خيارًا مناسبًا؟

يُعد Google Sheets API مناسبًا جدًا في الحالات التالية:

• نماذج التواصل البسيطة.
• نماذج جمع الملاحظات والاقتراحات.
• صفحات الهبوط التي تحتاج إلى حفظ الردود بسرعة.
• المشروعات الناشئة أو الصغيرة التي لا تحتاج إلى قاعدة بيانات كاملة.

لكن من المهم معرفة أن هذه الآلية ليست البديل المثالي للأنظمة الكبيرة أو التطبيقات ذات الحجم المرتفع من الطلبات، لأن هناك حدودًا على عدد طلبات API خلال فترة زمنية محددة.

أفضل الممارسات عند بناء نموذج ملاحظات

1. أضف تحققًا من صحة المدخلات قبل الإرسال.
2. استخدم رسائل نجاح وخطأ واضحة للمستخدم.
3. لا تكشف مفاتيح API أو بيانات الاعتماد في الواجهة الأمامية.
4. أضف حماية ضد الرسائل المزعجة مثل rate limiting أو CAPTCHA عند الحاجة.
5. نظّم أعمدة Google Sheets من البداية لتسهيل تحليل البيانات لاحقًا.

الخلاصة التقنية

يمنحك الدمج بين Next.js وGoogle Sheets API وسيلة ذكية وسريعة لبناء نموذج ملاحظات وظيفي دون الحاجة إلى Back-end تقليدي أو قاعدة بيانات منفصلة. هذا الحل مثالي للتطبيقات الصغيرة والنماذج منخفضة التعقيد، خصوصًا عندما تكون الأولوية هي سرعة التنفيذ وسهولة الإدارة. ومع ذلك، إذا كان مشروعك مرشحًا للنمو السريع أو يتطلب أمانًا وتحكمًا أكبر في البيانات، فمن الأفضل التفكير لاحقًا في بنية أكثر توسعًا مثل قواعد البيانات السحابية أو خدمات Backend مخصصة.