ورود به سیستم

هنگام توسعه هر نوع برنامه، اغلب می خواهید اطلاعاتی را ثبت کنید تا به تشخیص ایرادات در حین توسعه، شناسایی و تشخیص مشکلات مشتری و برای اهداف دیگر کمک کند.

Apps Script سه مکانیسم مختلف برای ورود به سیستم ارائه می دهد:

  • گزارش اجرای Apps Script داخلی. این گزارش سبک وزن است و در زمان واقعی پخش می شود، اما فقط برای مدت کوتاهی باقی می ماند.

  • رابط Cloud Logging در Developer Console، که گزارش‌هایی را ارائه می‌کند که برای چندین روز پس از ایجاد آنها باقی می‌مانند.

  • رابط گزارش خطا در Developer Console، که خطاهایی را که هنگام اجرا شدن اسکریپت شما رخ می دهد جمع آوری و ثبت می کند.

این موارد در بخش های بعدی توضیح داده شده است. علاوه بر این مکانیسم‌ها، می‌توانید کد لاگر خود را نیز بسازید که به عنوان مثال، اطلاعات را در صفحه‌گسترده گزارش یا پایگاه داده JDBC می‌نویسد.

از گزارش اجرای Apps Script استفاده کنید

یک رویکرد اساسی برای ورود به Apps Script استفاده از گزارش اجرای داخلی است. برای مشاهده این گزارش‌ها، در بالای ویرایشگر، روی Execution log کلیک کنید. هنگامی که یک تابع را اجرا می کنید یا از دیباگر استفاده می کنید، گزارش ها در زمان واقعی پخش می شوند.

می‌توانید از خدمات Logger یا console Logger در گزارش اجرای داخلی استفاده کنید.

این گزارش‌ها برای بررسی‌های ساده در حین توسعه و اشکال‌زدایی در نظر گرفته شده‌اند و مدت زیادی باقی نمی‌مانند.

برای مثال این تابع را در نظر بگیرید:

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

ثبت ابر

Apps Script همچنین دسترسی جزئی به سرویس Google Cloud Platform (GCP) Cloud Logging را فراهم می کند. هنگامی که نیاز به ثبت گزارش دارید که برای چندین روز ادامه دارد، یا به یک راه حل گزارش گیری پیچیده تر برای یک محیط تولید چند کاربره نیاز دارید، Cloud Logging انتخاب ترجیحی است. برای حفظ اطلاعات و سایر جزئیات سهمیه ، سهمیه‌ها و محدودیت‌های Cloud Logging را ببینید.

اگر به سهمیه گزارش بیشتر نیاز دارید، می‌توانید یک درخواست سهمیه Google Cloud Platform ارسال کنید . این مستلزم آن است که به پروژه Cloud Platform که اسکریپت شما استفاده می کند دسترسی داشته باشید.

استفاده از Cloud Logging

گزارش‌های Cloud به پروژه Google Cloud مرتبط با Apps Script شما پیوست می‌شوند. می‌توانید نسخه ساده‌شده این گزارش‌ها را در داشبورد Apps Script مشاهده کنید.

برای استفاده کامل از Cloud Logging و قابلیت های آن، از یک پروژه استاندارد Google Cloud با پروژه اسکریپت خود استفاده کنید. این به شما امکان می‌دهد مستقیماً در کنسول GCP به گزارش‌های Cloud دسترسی داشته باشید و گزینه‌های بیشتری برای مشاهده و فیلتر کردن در اختیار شما قرار دهد.

هنگام ورود به سیستم، عمل حفظ حریم خصوصی خوب است که از ثبت هرگونه اطلاعات شخصی در مورد کاربر، مانند آدرس ایمیل، خودداری کنید. گزارش‌های ابری به‌طور خودکار با کلیدهای کاربر فعال برچسب‌گذاری می‌شوند که می‌توانید در صورت لزوم از آنها برای پیدا کردن پیام‌های گزارش یک کاربر خاص استفاده کنید.

با استفاده از توابع ارائه شده توسط سرویس console Apps Script می توانید رشته ها، رشته های قالب بندی شده و حتی اشیاء JSON را ثبت کنید.

مثال زیر نحوه استفاده از سرویس console برای ثبت اطلاعات در Cloud Operations را نشان می دهد.

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 Log بدون افشای هویت آن کاربران فراهم می کند. کلیدها بر اساس اسکریپت هستند و تقریباً یک بار در ماه برای ایجاد امنیت بیشتر تغییر می کنند، در صورتی که کاربر هویت خود را برای توسعه دهنده فاش کند، مثلاً هنگام گزارش یک مشکل.

کلیدهای کاربر فعال موقت نسبت به شناسه های ورود به سیستم مانند آدرس های ایمیل برتری دارند زیرا:

  • شما لازم نیست چیزی به ورود به سیستم خود اضافه کنید. آنها در حال حاضر آنجا هستند!
  • آنها به مجوز کاربر نیاز ندارند.
  • آنها از حریم خصوصی کاربر محافظت می کنند.

برای یافتن کلیدهای کاربر فعال موقت در ورودی‌های Cloud Log، گزارش‌های Cloud خود را در کنسول Google Cloud مشاهده کنید . فقط در صورتی می توانید این کار را انجام دهید که پروژه اسکریپت شما از یک پروژه استاندارد Google Cloud استفاده می کند که شما به آن دسترسی دارید. هنگامی که پروژه Google Cloud را در کنسول باز کردید، یک ورودی گزارش مورد علاقه را انتخاب کنید و آن را برای مشاهده فراداده > labels > script.googleapis.com/user_key گسترش دهید.

همچنین می توانید با فراخوانی Session.getTemporaryActiveUserKey() در اسکریپت خود، کلید کاربر فعال موقت را دریافت کنید. یکی از راه های استفاده از این روش این است که هنگام اجرای اسکریپت شما، کلید را به کاربر نمایش دهید. سپس کاربران ممکن است هنگام گزارش مشکلات، کلیدهای خود را برای کمک به شناسایی گزارش‌های مربوطه درج کنند.

ثبت استثنائات

گزارش Exception استثناهای کنترل نشده در کد پروژه اسکریپت شما را به همراه یک stack trace به Cloud Logging می فرستد.

برای مشاهده گزارش های استثنا، مراحل زیر را دنبال کنید:

  1. پروژه Apps Script را باز کنید.
  2. در سمت چپ، روی Executions کلیک کنید.
  3. در بالا، روی افزودن فیلتر > وضعیت کلیک کنید.
  4. چک باکس های Failed و Timed out را انتخاب کنید.

همچنین اگر پروژه اسکریپت شما از پروژه استاندارد Google Cloud استفاده می کند که به آن دسترسی دارید، می توانید استثناهای ثبت شده را در کنسول GCP مشاهده کنید .

ثبت استثنا را فعال کنید

ثبت استثنا به طور پیش فرض برای پروژه های جدید فعال است. برای فعال کردن ثبت استثنا برای پروژه های قدیمی، مراحل زیر را دنبال کنید:

  1. پروژه اسکریپت را باز کنید.
  2. در سمت چپ، روی تنظیمات پروژه کلیک کنید.
  3. کادر بررسی Log uncaved exceptions to Cloud Operations را انتخاب کنید.

گزارش خطا

ثبت استثنا به طور خودکار با Cloud Error Reporting ادغام می شود، سرویسی که خطاهای تولید شده در اسکریپت شما را جمع آوری و نمایش می دهد. می‌توانید گزارش‌های خطای Cloud خود را در کنسول Google Cloud مشاهده کنید . اگر از شما خواسته شد "تنظیم گزارش خطا" را تنظیم کنید، به این دلیل است که اسکریپت شما هنوز هیچ استثنایی را ثبت نکرده است. هیچ راه اندازی به غیر از فعال کردن ثبت استثنا لازم نیست.

الزامات ورود به سیستم

هیچ الزامی برای استفاده از گزارش اجرای داخلی وجود ندارد.

می‌توانید نسخه ساده‌شده گزارش‌های Cloud را در داشبورد Apps Script مشاهده کنید. با این حال، برای استفاده حداکثری از Cloud Logging و گزارش خطا، باید به پروژه GCP اسکریپت دسترسی داشته باشید. این تنها در صورتی امکان پذیر است که پروژه اسکریپت شما از یک پروژه استاندارد Google Cloud استفاده کند.