التسجيل

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

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

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

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

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

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

استخدام سجل تنفيذ برمجة التطبيقات

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

يمكنك استخدام خدمتَي تسجيل الدخول 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 بتوقيت المحيط الهادئ] إرسال صف البيانات 2 بالبريد الإلكتروني إلى john@example.com
[16-09-12 13:50:42:271 بتوقيت المحيط الهادئ] بيانات الصف 2: التكلفة 103.24

Cloud Logging

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

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

استخدام التسجيل في السحابة الإلكترونية

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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