التسجيل

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

توفّر Apps Script ثلاث آليات مختلفة للتسجيل:

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

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

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

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

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

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

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

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

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

utils/logging.gs

العرض على GitHub

/**
 * 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" و "[e-mail]"، يتم تسجيل السجلّين التاليين:

[16-09-12 13:50:42:193 PDT] إرسال صف البيانات 2 بالبريد الإلكتروني إلى [e-mail]
[16-09-12 13:50:42:271 PDT] بيانات الصف 2: التكلفة 103.24

Cloud Logging

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

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

ملاحظة: توفّر ميزة "تسجيل في السحابة الإلكترونية" عددًا من الخدمات غير تخزين السجلّات، مثل التنبيهات والمقاييس. في الوقت الحالي، لا تتوفّر هذه الخدمات من Apps Script.

استخدام Cloud Logging

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

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

ملاحظة: في حال استخدام وقت تشغيل Rhino، لا تتوافق خدمة "تسجيل في السحابة الإلكترونية" مع خدمة Apps Script Logger. بدلاً من ذلك، استخدِم console service.

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

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

يوضّح المثال التالي كيفية استخدام خدمة console لتسجيل المعلومات في عمليات السحابة الإلكترونية.

utils/logging.gs

العرض على GitHub

/**
 * 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. لا يمكنك إجراء ذلك إلا إذا كان مشروع النصوص البرمجية يستخدم مشروعًا عاديًا على Google Cloud بإمكانك الوصول إليه. بعد فتح مشروع Google Cloud في وحدة التحكّم، اختَر إدخال سجلّ يهمّك ووسِّعه لعرض البيانات الوصفية > التصنيفات > script.googleapis.com/user_key.

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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