التسجيل

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

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

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

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

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

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

Cloud Logging

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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