جارٍ التسجيل

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

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

  • سجل تنفيذ برمجة التطبيقات المدمج. هذا السجلّ بسيط ويتم عرضه في الوقت الفعلي، ولكنه لا يستمر إلا لفترة قصيرة.

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

  • واجهة الإبلاغ عن الخطأ في 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
    Logger.log('Failed with error %s', err.message);
  }
}

عند تشغيل هذا النص البرمجي مع الإدخالين "2" و&;;john@example.com" تتم كتابة السجلّات التالية:

[16-09-12 13:50:42:193 PDT] إرسال بيانات البيانات من الصف الثاني إلى 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 الذي يستخدمه النص البرمجي.

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

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

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

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

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

يوضح المثال التالي كيفية استخدام خدمة console لتسجيل المعلومات في Cloud Operations.

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

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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