ورود به سیستم

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

اسکریپت برنامه‌های گوگل سه مکانیزم مختلف برای ثبت وقایع ارائه می‌دهد:

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

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

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

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

از گزارش اجرای اسکریپت برنامه‌ها استفاده کنید

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

از سرویس‌های ثبت وقایع 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}`);
  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);
}

وقتی این اسکریپت با ورودی‌های "2" و "john@example.com" اجرا می‌شود، گزارش‌های زیر نوشته می‌شوند:

> [16-09-12 13:50:42:193 PDT] Emailing data row 2 to john@example.com
> [16-09-12 13:50:42:271 PDT] Row 2 data: Cost 103.24

ثبت وقایع ابری

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

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

Cloud Logging علاوه بر ذخیره لاگ‌ها، خدمات دیگری مانند هشدارها و معیارها را نیز ارائه می‌دهد. این خدمات از طریق Apps Script در دسترس نیستند.

استفاده از ثبت وقایع ابری

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

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

اگر از محیط اجرایی راینو (Rhino) استفاده می‌کنید، Cloud Logging از سرویس Apps Script Logger پشتیبانی نمی‌کند. در عوض، از سرویس console استفاده کنید.

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

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

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

utils/logging.gs
/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * 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 در کنسول، یک ورودی گزارش مورد علاقه خود را انتخاب کرده و آن را گسترش دهید تا metadata > labels > script.googleapis.com/user_key را مشاهده کنید.

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

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

ثبت استثنائات، استثنائات مدیریت نشده در کد پروژه اسکریپت شما را به همراه ردیابی پشته به Cloud Logging ارسال می‌کند.

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

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

اگر پروژه اسکریپت شما از یک پروژه استاندارد گوگل کلود که به آن دسترسی دارید استفاده می‌کند، استثنائات ثبت‌شده را در کنسول گوگل کلود مشاهده کنید.

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

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

  1. پروژه اسکریپت را باز کنید.
  2. در سمت چپ، روی پروژه کلیک کنید.
  3. کادر انتخاب « ثبت استثنائات ثبت نشده در عملیات ابری» را علامت بزنید.

گزارش خطا

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

الزامات ثبت وقایع

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

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