جارٍ التسجيل

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

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

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

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

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

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

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

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

استخدام/تسجيل الدخول
/**
 * 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 بتوقيت المحيط الهادئ (PDT)] بيانات الصف 2: التكلفة 103.24

Cloud Logging

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

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

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

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

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

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

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

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

استخدام/تسجيل الدخول
/**
 * 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 Log بدون الكشف عن هويات هؤلاء المستخدمين. يتم تعديل المفاتيح حسب كل نص برمجي تقريبًا، ويتم تغييرها مرة واحدة في الشهر تقريبًا لتوفير أمان إضافي في حال كشف المستخدم عن هويته لمطوّر برامج، أثناء الإبلاغ عن مشكلة مثلاً.

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

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

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

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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