التسجيل

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

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

• سجلّ تنفيذ "برمجة تطبيقات Google" المُدمَج. هذا السجل بسيط ويمكن بثه في الوقت الفعلي، لكنه يستمرّ لفترة قصيرة فقط.

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

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

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

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

أحد الأساليب الأساسية لتسجيل الدخول إلى "برمجة تطبيقات 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 PDT] إرسال صف البيانات 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".

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

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

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

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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