عیب یابی

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

پیام‌های خطا

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

خطاهای نحوی

خطاهای نحوی (syntax errors) ناشی از نوشتن کدی هستند که از دستور زبان جاوا اسکریپت پیروی نمی‌کند و خطاها به محض اینکه سعی می‌کنید اسکریپت را ذخیره کنید، شناسایی می‌شوند. برای مثال، قطعه کد زیر حاوی یک خطای نحوی است:

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ";
  MailApp.sendEmail('john@example.com',
                    'Data in row ' + rowNumber,
                    rowData);
}

مشکل نحوی اینجا، نبود یک کاراکتر ) در انتهای خط چهارم است. وقتی سعی می‌کنید اسکریپت را ذخیره کنید، خطای زیر را دریافت خواهید کرد:

بعد از لیست آرگومان‌ها وجود ندارد. (خط ۴)

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

خطاهای زمان اجرا

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

function emailDataRow(rowNumber) {
  var sheet = SpreadsheetApp.getActiveSheet();
  var data = sheet.getDataRange().getValues();
  var rowData = data[rowNumber-1].join(" ");
  MailApp.sendEmail('john',
                    'Data in row ' + rowNumber,
                    rowData);
}

کد به درستی قالب‌بندی شده است، اما ما هنگام فراخوانی MailApp.sendEmail ، مقدار "john" را برای آدرس ایمیل ارسال می‌کنیم. از آنجایی که این یک آدرس ایمیل معتبر نیست، هنگام اجرای اسکریپت خطای زیر رخ می‌دهد:

ایمیل نامعتبر: john (خط ۵)

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

خطاهای رایج

در زیر لیستی از خطاهای رایج و علل آنها آورده شده است.

سرویس بیش از حد فراخوانی شده است: <action name>

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

سرور در دسترس نیست. یا خطایی در سرور رخ داده است، لطفاً دوباره امتحان کنید.

چند دلیل احتمالی برای این خطاها وجود دارد:

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

برای انجام آن اقدام، مجوز لازم است.

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

برای تأیید اسکریپت، ویرایشگر اسکریپت را باز کنید و هر تابعی را اجرا کنید. اعلان تأیید ظاهر می‌شود تا بتوانید پروژه اسکریپت را تأیید کنید. اگر اسکریپت حاوی سرویس‌های غیرمجاز جدید باشد، باید اسکریپت را دوباره تأیید کنید.

این خطا اغلب توسط triggerهایی ایجاد می‌شود که یا قبل از اینکه کاربر آنها را تأیید کند، فعال می‌شوند یا اعتبار آنها منقضی شده است. اگر به پروژه اسکریپت دسترسی ندارید (به عنوان مثال، به این دلیل که خطا برای افزونه‌ای که استفاده می‌کنید رخ می‌دهد)، معمولاً می‌توانید با استفاده مجدد از افزونه، اسکریپت را تأیید کنید. اگر یک trigger همچنان فعال باشد و باعث این خطا شود، می‌توانید triggerهای خود را با انجام موارد زیر حذف کنید:

  1. در سمت چپ پروژه Apps Script، روی «راه‌اندازی زنگ کلیک کنید.
  2. در سمت راست تریگری که می‌خواهید حذف کنید، روی More > Delete trigger کلیک کنید.

همچنین می‌توانید با حذف نصب افزونه، محرک‌های افزونه مشکل‌ساز را حذف کنید.

مجوزهای جزئی نیز می‌توانند باعث این خطاها شوند. Apps Script به طور خودکار مجوزهای از دست رفته را از کاربر درخواست می‌کند، مگر اینکه اجرا توسط یک trigger فراخوانی شود. برای محافظت از اجراهای trigger در برابر این خطا، به صفحه محدوده‌های مجوز ما مراجعه کنید.

دسترسی رد شد: DriveApp یا خط‌مشی دامنه، برنامه‌های Drive شخص ثالث را غیرفعال کرده است

مدیران دامنه‌های Google Workspace می‌توانند Drive API را برای دامنه خود غیرفعال کنند، که این امر مانع از نصب و استفاده کاربران از برنامه‌های Google Drive می‌شود. این تنظیم همچنین مانع از استفاده کاربران از افزونه‌های Apps Script می‌شود که از سرویس Drive یا Advanced Drive Service استفاده می‌کنند (حتی اگر اسکریپت قبل از غیرفعال کردن Drive API توسط مدیر مجاز شده باشد).

با این حال، اگر یک افزونه یا برنامه وب که از سرویس Drive استفاده می‌کند برای نصب در سطح دامنه منتشر شده و توسط مدیر برای برخی یا همه کاربران در دامنه نصب شود، اسکریپت برای آن کاربران حتی اگر Drive API در دامنه غیرفعال باشد، کار می‌کند.

اسکریپت اجازه دریافت هویت کاربر فعال را ندارد.

نشان می‌دهد که هویت و ایمیل کاربر فعال برای اسکریپت در دسترس نیست. این هشدار ناشی از فراخوانی Session.getActiveUser() است. همچنین اگر اسکریپت در حالت مجوزی غیر از AuthMode.FULL اجرا شود، می‌تواند ناشی از فراخوانی Session.getEffectiveUser() باشد. اگر این هشدار ارسال شود، فراخوانی‌های بعدی User.getEmail() فقط "" را برمی‌گردانند.

بسته به حالت مجوزی که اسکریپت تحت آن اجرا می‌شود، روش‌های مختلفی برای عیب‌یابی این هشدار وجود دارد. حالت مجوز در توابع فعال‌شده به عنوان ویژگی authMode از پارامتر رویداد e نمایش داده می‌شود.

  • در AuthMode.FULL ، به جای آن، استفاده از Session.getEffectiveUser() را در نظر بگیرید.
  • در AuthMode.LIMITED ، مطمئن شوید که مالک، اسکریپت را مجاز کرده است.
  • در سایر حالت‌های مجوزدهی، از فراخوانی هر یک از این دو متد خودداری کنید.
  • اگر از مشتریان Google Workspace هستید و به تازگی این هشدار را از یک تریگر قابل نصب دریافت کرده‌اید، مطمئن شوید که تریگر به عنوان یک کاربر در سازمان شما در حال اجرا است.

کتابخانه مفقود است

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

  • کد کتابخانه را کپی و در اسکریپت خود جایگذاری کنید و وابستگی به کتابخانه را حذف کنید.
  • اسکریپت کتابخانه را کپی کرده و آن را به عنوان یک کتابخانه از حساب خود مستقر کنید. حتماً وابستگی موجود در اسکریپت اصلی خود را به جای کتابخانه عمومی، به کتابخانه جدید به‌روزرسانی کنید.

به دلیل عدم وجود نسخه کتابخانه یا نسخه استقرار، خطایی رخ داده است. کد خطا Not_Found

این پیام خطا نشان دهنده یکی از موارد زیر است:

  • نسخهٔ پیاده‌سازی‌شدهٔ اسکریپت حذف شده است. برای به‌روزرسانی نسخهٔ پیاده‌سازی‌شدهٔ اسکریپت خود، به ویرایش یک پیاده‌سازی نسخه‌بندی‌شده مراجعه کنید.
  • نسخه کتابخانه‌ای که اسکریپت از آن استفاده می‌کند حذف شده است. برای بررسی اینکه کدام کتابخانه از دست رفته است، در کنار نام کتابخانه، روی More > Open in new tab کلیک کنید. کتابخانه‌ی از دست رفته پیام خطا می‌دهد. پس از یافتن کتابخانه‌ای که باید به‌روزرسانی کنید، یکی از اقدامات زیر را انجام دهید:
  • اسکریپت کتابخانه‌ای که اسکریپت شما از آن استفاده می‌کند، شامل کتابخانه دیگری است که از نسخه حذف شده استفاده می‌کند. یکی از اقدامات زیر را انجام دهید:
    • اگر به کتابخانه‌ای که اسکریپت شما از آن استفاده می‌کند دسترسی ویرایش دارید، کتابخانه ثانویه موجود در آن اسکریپت را به‌روزرسانی کنید.
    • برای استفاده از نسخه دیگری، کتابخانه را به‌روزرسانی کنید. به بخش به‌روزرسانی کتابخانه مراجعه کنید.
    • کتابخانه را از پروژه اسکریپت و کد خود حذف کنید. به بخش حذف کتابخانه مراجعه کنید.

خطای ۴۰۰: invalid_scope هنگام فراخوانی Google Chat API با سرویس پیشرفته

اگر با Error 400: invalid_scope به همراه پیام خطای « Some requested scopes cannot be shown مواجه شدید، به این معنی است که شما هیچ حوزه مجوزی را در فایل appsscript.json پروژه Apps Script مشخص نکرده‌اید. در بیشتر موارد، Apps Script به طور خودکار تعیین می‌کند که یک اسکریپت به چه حوزه‌هایی نیاز دارد، اما وقتی از سرویس پیشرفته Chat استفاده می‌کنید، باید حوزه‌های مجوزی را که اسکریپت شما استفاده می‌کند، به صورت دستی به فایل مانیفست پروژه Apps Script خود اضافه کنید. به بخش «تنظیم حوزه‌های صریح» مراجعه کنید.

برای رفع خطا، محدوده‌های مجوزدهی مناسب را به عنوان بخشی از آرایه oauthScopes به فایل appsscript.json پروژه Apps Script اضافه کنید. برای مثال، برای فراخوانی متد spaces.messages.create ، کد زیر را اضافه کنید:

"oauthScopes": [
  "https://www.googleapis.com/auth/chat.messages.create"
]

فراخوانی‌های UrlFetch به <URL> توسط مدیر شما مجاز نیستند.

مدیران Google Workspace می‌توانند فهرست مجوزهای دسترسی را در کنسول مدیریت فعال کنند تا کنترل کنند که از طریق Apps Script به کدام دامنه‌های خارجی می‌توانید دسترسی داشته باشید.

برای رفع خطا، با مدیر خود تماس بگیرید تا آدرس اینترنتی را به لیست مجاز اضافه کند.

اشکال‌زدایی

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

ثبت وقایع

هنگام اشکال‌زدایی، اغلب ثبت اطلاعات در حین اجرای یک پروژه اسکریپت مفید است. Google Apps Script دو ​​روش برای ثبت اطلاعات دارد: سرویس ثبت وقایع ابری و سرویس‌های اساسی‌تر Logger و کنسول که در ویرایشگر Apps Script تعبیه شده‌اند.

برای جزئیات بیشتر به راهنمای ثبت وقایع مراجعه کنید.

گزارش خطا

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

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

اعدام‌ها

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

برای مشاهده‌ی اجراهای اسکریپت خود در پروژه‌ی Apps Script، در سمت چپ، روی Executions کلیک کنید.

بررسی وضعیت سرویس اسکریپت برنامه‌ها

اگرچه نادر است، اما گاهی اوقات سرویس‌های خاص Google Workspace (مانند Gmail یا Drive) با مشکلات موقتی مواجه می‌شوند که می‌تواند منجر به قطع سرویس شود. در این صورت، پروژه‌های Apps Script که با این سرویس‌ها تعامل دارند، ممکن است آنطور که انتظار می‌رود عمل نکنند.

می‌توانید با مشاهده داشبورد وضعیت Google Workspace بررسی کنید که آیا سرویس Google Workspace دچار قطعی شده است یا خیر. اگر در حال حاضر قطعی وجود دارد، یا منتظر بمانید تا برطرف شود یا در مرکز راهنمایی Google Workspace یا مستندات مشکلات شناخته‌شده Google Workspace درخواست کمک بیشتر کنید.

از اشکال‌زدا و نقاط توقف استفاده کنید

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

اضافه کردن نقطه توقف

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

اضافه کردن نقطه توقف

اجرای اسکریپت در حالت اشکال‌زدایی

برای اجرای اسکریپت در حالت اشکال‌زدایی، در بالای ویرایشگر روی Debug کلیک کنید.

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

برای کنترل نحوه اجرای اسکریپت، در بالای پنل اشکال‌زدا، از دکمه‌های «ورود»، «خروج» و «خروج» استفاده کنید. این دکمه‌ها به شما امکان می‌دهند اسکریپت را خط به خط اجرا کنید و نحوه تغییر مقادیر را در طول زمان بررسی کنید.

خطا : کد منبع برای خط فعلی در دسترس نیست

کد منبع خط فعلی در دسترس نیست

این خطا زمانی ظاهر می‌شود که یک فایل اشکال‌زدایی فعال در دسترس نباشد. اسکریپت Google Apps از نمایش اسکریپت‌های جاوا اسکریپت (JS) تولید شده به صورت پویا در ویرایشگر اسکریپت، مانند اسکریپت‌های تولید شده با استفاده از eval() و new Function() پشتیبانی نمی‌کند. این اسکریپت‌ها در موتور V8 ایجاد و اجرا می‌شوند، اما به عنوان فایل‌های مستقل در ویرایشگر نمایش داده نمی‌شوند. اگر وارد این اسکریپت‌ها شوید، با این خطا مواجه خواهید شد.

برای مثال، کد زیر را در نظر بگیرید:

function myFunction() {
  eval('a=2');
}

وقتی تابع eval() فراخوانی می‌شود، آرگومان آن به عنوان کد JS در نظر گرفته می‌شود و به عنوان یک اسکریپت پویا ایجاد شده در داخل موتور V8 اجرا می‌شود. اگر وارد تابع eval() شوید، این خطا ظاهر می‌شود. اگر اسکریپت شامل یک کامنت //# sourceURL باشد، نام آن در پشته فراخوانی نمایش داده می‌شود. در غیر این صورت، به عنوان یک ورودی بدون نام نمایش داده می‌شود.

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

مشکلات مربوط به چندین حساب گوگل

اگر همزمان وارد چندین حساب گوگل شده‌اید، ممکن است در دسترسی به افزونه‌ها و برنامه‌های وب خود مشکل داشته باشید. ورود چندگانه یا ورود همزمان به چندین حساب گوگل برای اسکریپت برنامه‌ها، افزونه‌ها یا برنامه‌های وب پشتیبانی نمی‌شود.

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

  • اگر یک برنامه وب یا افزونه را باز کردید و با مشکل ورود چندگانه مواجه شدید، یکی از راه‌حل‌های زیر را امتحان کنید:

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

دریافت کمک

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