التسجيل

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

توفّر "برمجة التطبيقات" ثلاث آليات مختلفة لتسجيل البيانات:

  • سجلّ تنفيذ "برمجة تطبيقات Google" المضمّن هذا السجلّ صغير الحجم ويتم بثّه في الوقت الفعلي، ولكنّه لا يبقى متاحًا إلا لفترة قصيرة.

  • واجهة Cloud Logging في Developer Console، والتي توفّر سجلات تظل متاحة لعدة أيام بعد إنشائها.

  • واجهة الإبلاغ عن الأخطاء في Developer Console، والتي تجمع الأخطاء التي تحدث أثناء تنفيذ النص البرمجي وتسجّلها.

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

استخدام سجلّ تنفيذ Apps Script

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

يمكنك استخدام خدمات التسجيل Logger أو console في سجلّ التنفيذ المضمّن.

هذه السجلات مخصّصة لعمليات التحقّق البسيطة أثناء التطوير وتصحيح الأخطاء، ولا يتم الاحتفاظ بها لفترة طويلة.

على سبيل المثال، ضع في اعتبارك الدالة التالية:

utils/logging.gs
/**
 * Logs Google Sheet information.
 * @param {number} rowNumber The spreadsheet row number.
 * @param {string} email The email to send with the row data.
 */
function emailDataRow(rowNumber, email) {
  console.log('Emailing data row ' + rowNumber + ' to ' + email);
  try {
    const sheet = SpreadsheetApp.getActiveSheet();
    const data = sheet.getDataRange().getValues();
    const rowData = data[rowNumber - 1].join(' ');
    console.log('Row ' + rowNumber + ' data: ' + rowData);
    MailApp.sendEmail(email, 'Data in row ' + rowNumber, rowData);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

عند تشغيل هذا النص البرمجي مع الإدخالات "2" و "john@example.com"، يتم إنشاء السجلات التالية:

[16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
[16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

Cloud Logging

توفّر "برمجة التطبيقات" أيضًا إمكانية الوصول الجزئي إلى خدمة Cloud Logging في Google Cloud Platform (GCP). عندما تحتاج إلى تسجيل بيانات يستمر لعدة أيام، أو تحتاج إلى حلّ أكثر تعقيدًا لتسجيل البيانات في بيئة إنتاج متعددة المستخدمين، يكون Cloud Logging هو الخيار المفضّل. راجِع حصص Cloud Logging وحدوده للحصول على تفاصيل حول الاحتفاظ بالبيانات وحصص أخرى.

إذا كنت بحاجة إلى حصة تسجيل إضافية، يمكنك إرسال طلب حصة على Google Cloud Platform. يتطلّب ذلك أن يكون لديك إذن الوصول إلى مشروع Cloud Platform الذي يستخدمه النص البرمجي.

استخدام Cloud Logging

يتم إرفاق سجلات Cloud بمشروع Google Cloud المرتبط بـ "برمجة تطبيقات Google". يمكنك الاطّلاع على نسخة مبسّطة من هذه السجلات في لوحة بيانات "برمجة تطبيقات Google".

للاستفادة بشكل كامل من Cloud Logging وإمكاناتها، استخدِم مشروعًا عاديًا على Google Cloud مع مشروع النص البرمجي. يتيح لك ذلك الوصول إلى سجلات Cloud مباشرةً في وحدة تحكّم Google Cloud Platform، كما يمنحك المزيد من خيارات العرض والفلترة.

.

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

يمكنك تسجيل السلاسل والسلاسل المنسَّقة وحتى عناصر JSON باستخدام الدوال التي توفّرها خدمة console في "برمجة تطبيقات Google".

يوضّح المثال التالي كيفية استخدام خدمة console لتسجيل المعلومات في Cloud Operations.

utils/logging.gs
/**
 * Logs the time taken to execute 'myFunction'.
 */
function measuringExecutionTime() {
  // A simple INFO log message, using sprintf() formatting.
  console.info('Timing the %s function (%d arguments)', 'myFunction', 1);

  // Log a JSON object at a DEBUG level. The log is labeled
  // with the message string in the log viewer, and the JSON content
  // is displayed in the expanded log structure under "jsonPayload".
  const parameters = {
    isValid: true,
    content: 'some string',
    timestamp: new Date()
  };
  console.log({message: 'Function Input', initialData: parameters});
  const label = 'myFunction() time'; // Labels the timing log entry.
  console.time(label); // Starts the timer.
  try {
    myFunction(parameters); // Function to time.
  } catch (e) {
    // Logs an ERROR message.
    console.error('myFunction() yielded an error: ' + e);
  }
  console.timeEnd(label); // Stops the timer, logs execution duration.
}

مفاتيح المستخدمين النشطين

توفّر مفاتيح المستخدمين النشطين المؤقتة طريقة ملائمة لرصد المستخدمين الفريدين في إدخالات سجلّات Cloud بدون الكشف عن هويات هؤلاء المستخدمين. تكون المفاتيح خاصة بكل نص برمجي وتتغير مرة واحدة شهريًا تقريبًا لتوفير أمان إضافي في حال كشف المستخدم عن هويته للمطوّر، مثلاً أثناء الإبلاغ عن مشكلة.

تتفوق مفاتيح المستخدمين النشطين المؤقتة على معرّفات التسجيل، مثل عناوين البريد الإلكتروني، للأسباب التالية:

  • ليس عليك إضافة أي شيء إلى سجلّاتك، فهي متوفّرة فيها.
  • ولا تتطلّب تفويض المستخدم.
  • أن تحمي خصوصية المستخدمين

للعثور على مفاتيح المستخدمين النشطين المؤقتة في إدخالات سجلّات Cloud، يمكنك عرض سجلّات Cloud في Google Cloud Console. لا يمكنك إجراء ذلك إلا إذا كان مشروع النص البرمجي يستخدم مشروعًا عاديًا على Google Cloud يمكنك الوصول إليه. بعد فتح مشروع Google Cloud في وحدة التحكّم، اختَر إدخال سجلّ يهمّك ووسِّعه لعرض البيانات الوصفية > التصنيفات > script.googleapis.com/user_key.

يمكنك أيضًا الحصول على مفتاح المستخدم النشط المؤقت من خلال استدعاء Session.getTemporaryActiveUserKey() في النص البرمجي. إحدى طرق استخدام هذه الطريقة هي عرض المفتاح للمستخدم أثناء تشغيل النص البرمجي. بعد ذلك، يمكن للمستخدمين اختيار تضمين مفاتيحهم عند الإبلاغ عن المشاكل لمساعدتك في تحديد السجلات ذات الصلة.

تسجيل الاستثناءات

تؤدي عملية تسجيل الاستثناءات إلى إرسال الاستثناءات غير المعالَجة في رمز مشروع النص البرمجي إلى Cloud Logging، بالإضافة إلى تتبُّع تسلسل استدعاء الدوال البرمجية.

للاطّلاع على سجلّات الاستثناءات، اتّبِع الخطوات التالية:

  1. افتح مشروع Apps Script.
  2. على يمين الصفحة، انقر على عمليات التنفيذ .
  3. في أعلى الصفحة، انقر على إضافة فلتر > الحالة.
  4. ضَع علامة في مربّعَي الاختيار تعذّر وانتهت المهلة.

يمكنك أيضًا عرض الاستثناءات المسجّلة في وحدة تحكّم Google Cloud Platform إذا كان مشروع البرنامج النصي يستخدم مشروعًا عاديًا على Google Cloud يمكنك الوصول إليه.

تفعيل تسجيل الأخطاء

يتم تفعيل تسجيل الأخطاء تلقائيًا للمشاريع الجديدة. لتفعيل تسجيل الاستثناءات للمشاريع القديمة، اتّبِع الخطوات التالية:

  1. افتح مشروع النص البرمجي.
  2. على يمين الصفحة، انقر على إعدادات المشروع .
  3. ضَع علامة في مربّع الاختيار تسجيل الاستثناءات غير المرصودة في Cloud Operations.

Error Reporting

يتم دمج تسجيل الاستثناءات تلقائيًا مع Cloud Error Reporting، وهي خدمة تجمع الأخطاء التي تم إنتاجها في البرنامج النصي وتعرضها. يمكنك عرض تقارير أخطاء Cloud في Google Cloud Console. إذا طُلب منك "إعداد ميزة "إعداد تقارير الأخطاء""، يعني ذلك أنّ النص البرمجي لم يسجّل أي استثناءات بعد. لا يلزم إجراء أي إعدادات أخرى غير تفعيل تسجيل الأخطاء.

متطلبات التسجيل

لا توجد متطلبات لاستخدام سجلّ التنفيذ المضمّن.

يمكنك الاطّلاع على نسخة مبسطة من سجلّات Cloud في لوحة بيانات "برمجة تطبيقات Google". ومع ذلك، للاستفادة إلى أقصى حد من Cloud Logging و"تقارير الأخطاء"، يجب أن يكون لديك إذن الوصول إلى مشروع Google Cloud الخاص بالنص البرمجي. لا يمكن إجراء ذلك إلا إذا كان مشروع النص البرمجي يستخدم مشروعًا عاديًا على Google Cloud.