ورود به سیستم

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

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

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

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

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

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

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

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

می‌توانید از سرویس‌های ثبت وقایع 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}`);
  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] ارسال ایمیل به ردیف داده 2 john@example.com
[16-09-12 13:50:42:271 PDT] داده‌های ردیف 2: هزینه 103.24

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

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

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

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

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

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

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

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

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

/**
 * 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. در سمت چپ، روی « اجراها playlist_play کلیک کنید.
3. در بالا، روی افزودن فیلتر > وضعیت کلیک کنید.
4. کادرهای انتخاب Failed (شکست خورده) و Timed out (پایان زمان) را علامت بزنید.

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

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

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

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

گزارش خطا

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

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

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

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