كيفية ربط Google Sheets بالعالم الخارجي عبر Script

ماذا سنبني اليوم؟

اليوم، سنتعلم كيفية ربط Google Sheets بالعالم الخارجي باستخدام Google Apps Script. سنقوم بإنشاء نظام بسيط يقوم بإرسال البيانات من جدول Google Sheets إلى نقطة نهاية خارجية (webhook) كلما تم تحديث صف معين. هذا يسمح لنا بأتمتة المهام، مثل إرسال إشعارات، تحديث قواعد بيانات أخرى، أو تشغيل سير عمل خارجي بناءً على التغييرات في جدول البيانات.

المتطلبات الأساسية

• حساب Google.
• فهم أساسي لـ Google Sheets.
• فهم أساسي للغة JavaScript (حيث أن Google Apps Script مبني عليها).
• عنوان URL لـ Webhook تجريبي (يمكنك الحصول عليه مجانًا من خدمات مثل Pipedream.com أو Zapier لاختبار الاستقبال).

الخطوة 1: إعداد جدول Google Sheets

افتح Google Sheets وأنشئ جدول بيانات جديدًا. أضف رؤوس الأعمدة التالية في الصف الأول:

الاسم | البريد الإلكتروني | الرسالة | الحالة

املأ بعض الصفوف ببيانات تجريبية. سنقوم بإعداد السكريبت ليتم تشغيله عندما يتم تحديث عمود الحالة (العمود D).

الخطوة 2: فتح محرر Google Apps Script

من جدول البيانات الخاص بك، انتقل إلى الإضافات (Extensions) > Apps Script. سيؤدي هذا إلى فتح محرر النصوص البرمجية في علامة تبويب جديدة.

الخطوة 3: كتابة كود Google Apps Script

في محرر النصوص البرمجية، ستجد ملفًا افتراضيًا باسم Code.gs. امسح أي كود موجود والصق الكود التالي:

function onEdit(e) {
  const sheet = e.source.getActiveSheet();
  const range = e.range;
  const row = range.getRow();
  const column = range.getColumn();

  // تحديد اسم الورقة التي يجب أن يعمل عليها هذا المشغل
  const targetSheetName = "Sheet1"; // قم بتغيير هذا إذا كان لورقتك اسم مختلف
  if (sheet.getName() !== targetSheetName) {
    return; // الخروج إذا لم تكن الورقة المستهدفة
  }

  // تحديد فهرس العمود (1-based) الذي، عند تعديله، يقوم بتشغيل الـ Webhook.
  // لنفترض أنه العمود D (الفهرس 4) لـ 'الحالة'.
  const triggerColumn = 4;

  // التأكد من أن الصف ليس هو صف الرؤوس وأن الخلية المعدلة في عمود التشغيل
  if (row > 1 && column === triggerColumn) { // row > 1 لتخطي صف الرؤوس
    const rowData = sheet.getRange(row, 1, 1, sheet.getLastColumn()).getValues()[0];
    const headers = sheet.getRange(1, 1, 1, sheet.getLastColumn()).getValues()[0];

    const payload = {};
    headers.forEach((header, index) => {
      payload[header] = rowData[index];
    });

    const webhookUrl = "YOUR_WEBHOOK_URL_HERE"; // استبدل هذا بعنوان URL الخاص بالـ Webhook الخاص بك

    const options = {
      "method": "post",
      "contentType": "application/json",
      "payload": JSON.stringify(payload),
      "muteHttpExceptions": true // يمنع السكريبت من الانهيار عند أخطاء HTTP
    };

    try {
      const response = UrlFetchApp.fetch(webhookUrl, options);
      Logger.log("Webhook response: " + response.getContentText());
      // اختياري: تحديث خلية حالة في الورقة للإشارة إلى النجاح/الفشل
      // sheet.getRange(row, sheet.getLastColumn() + 1).setValue("Sent to Webhook");
    } catch (error) {
      Logger.log("Error sending to webhook: " + error.toString());
      // sheet.getRange(row, sheet.getLastColumn() + 1).setValue("Error: " + error.message);
    }
  }
}

الخطوة 4: الحصول على Webhook URL تجريبي

إذا لم يكن لديك Webhook URL، يمكنك إنشاء واحد مجانًا على Pipedream.com. ما عليك سوى التسجيل وإنشاء Workflow جديد، وستحصل على Webhook URL فريد يمكنك استخدامه للاختبار. انسخ هذا الـ URL واستبدل "YOUR_WEBHOOK_URL_HERE" في الكود أعلاه به.

الخطوة 5: حفظ وتشغيل الكود

1. حفظ السكريبت: انقر على أيقونة الحفظ (شكل القرص المرن) أو Ctrl + S (أو Cmd + S).
2. تفويض السكريبت: في المرة الأولى التي تقوم فيها بتشغيل السكريبت (أو عند حفظه، حيث يتم تشغيل onEdit تلقائيًا عند التعديل)، سيطلب منك Google Apps Script تفويضًا. اتبع التعليمات لمنح السكريبت الأذونات اللازمة للوصول إلى Google Sheets والاتصال بخدمات خارجية.

الخطوة 6: اختبار الكود

عد إلى جدول Google Sheets الخاص بك. قم بتعديل أي خلية في عمود الحالة (العمود D) لأي صف (باستثناء صف الرؤوس). على سبيل المثال، قم بتغيير "قيد الانتظار" إلى "تم الانتهاء".

بعد التعديل، سيعمل السكريبت في الخلفية. تحقق من Webhook URL الخاص بك (على Pipedream أو خدمتك الأخرى)؛ يجب أن ترى البيانات من الصف الذي قمت بتعديله قد وصلت كـ JSON payload.

ملاحظات تقنية هامة

• القيود الأمنية: كن حذرًا عند إرسال بيانات حساسة عبر Webhooks. تأكد من أن نقطة النهاية آمنة وتستخدم HTTPS.
• حدود التنفيذ: لدى Google Apps Script حصص يومية لتشغيل السكريبتات وطلبات UrlFetchApp. راجع وثائق Google Apps Script للحصول على التفاصيل.
• تسجيل الأخطاء: استخدم Logger.log() لتسجيل الرسائل والأخطاء. يمكنك عرض سجلاتك في محرر Apps Script بالانتقال إلى Execution log (سجل التنفيذ).
• مشغلات مختلفة: يمكن لـ Apps Script استخدام مشغلات أخرى غير onEdit، مثل onOpen (عند فتح الورقة) أو المشغلات الزمنية (لتشغيل السكريبت على فترات منتظمة).
• التعامل مع الأخطاء: قمنا بتضمين try...catch لمعالجة الأخطاء المحتملة أثناء طلب الـ Webhook. هذا أمر بالغ الأهمية في البيئات الإنتاجية.

النتيجة النهائية المتوقعة

عندما يتم تحديث خلية معينة (على سبيل المثال، في العمود D، 'الحالة') في Google Sheet الخاص بك، سيقوم السكريبت تلقائيًا بالتقاط بيانات الصف بأكمله وإرسالها كحمولة JSON إلى Webhook URL الخارجي الذي قمت بتكوينه. ستكون هذه البيانات مرئية بعد ذلك في واجهة مراقبة Webhook الخاصة بك (مثل Pipedream). يوضح هذا دفع البيانات في الوقت الفعلي من Google Sheets إلى نظام خارجي، مما يتيح المزيد من الأتمتة أو التكامل مع تطبيقات أخرى.

← السابقالفهرسالتالي →