عیب یابی

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

پیام‌های خطا

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

خطاهای نحوی

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

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);
}

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

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

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

خطاهای رایج

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

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

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

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

علل احتمالی عبارتند از:

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

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

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

برای تأیید اسکریپت، ویرایشگر اسکریپت را باز کنید و هر تابعی را اجرا کنید. اگر اسکریپت از سرویس‌های غیرمجاز جدید استفاده می‌کند، باید دوباره آن را تأیید کنید.

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

  1. در پروژه Apps Script، روی Triggers کلیک کنید.
  2. در کنار تریگر، روی More > Delete trigger کلیک کنید.

روش دیگر، افزونه را حذف نصب کنید .

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

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

مدیران Google Workspace می‌توانند Drive API را برای دامنه خود غیرفعال کنند، که این امر مانع از استفاده کاربران از برنامه‌های Drive یا افزونه‌های Apps Script که از سرویس Drive استفاده می‌کنند، می‌شود.

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

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

هویت و ایمیل کاربر فعال در دسترس نیست. این مشکل ناشی از فراخوانی Session.getActiveUser() یا Session.getEffectiveUser() در حالت‌های مجوزدهی غیر از AuthMode.FULL است. اگر اسکریپت شما روی یک تریگر اجرا می‌شود، می‌توانید حالت مجوزدهی را در ویژگی authMode از شیء رویداد Apps Script پیدا کنید.

عیب‌یابی این مشکل بر اساس حالت مجوز:

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

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

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

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

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

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

  • نسخه اسکریپت مورد استفاده توسط یک استقرار حذف شده است. برای حل این مشکل، استقرار را ویرایش کرده و نسخه اسکریپت دیگری را انتخاب کنید.
  • نسخه‌ای از کتابخانه که توسط اسکریپت استفاده می‌شد، حذف شده است. برای حل این مشکل، در ویرایشگر اسکریپت در قسمت «کتابخانه‌ها»، کتابخانه را پیدا کرده و آن را به نسخه دیگری به‌روزرسانی کنید یا کتابخانه را حذف کنید. برای به‌روزرسانی، روی شماره نسخه کلیک کنید و نسخه دیگری را انتخاب کنید. برای حذف، روی «بیشتر» > » کلیک کنید.
  • یک کتابخانه شامل کتابخانه دیگری است و نسخه آن کتابخانه حذف شده است. برای حل این مشکل، با نویسنده کتابخانه تماس بگیرید یا از نسخه دیگری از کتابخانه‌ای که اسکریپت شما استفاده می‌کند استفاده کنید.

خطای ۴۰۰: 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 می‌توانند از یک فهرست مجاز برای کنترل دسترسی به دامنه خارجی استفاده کنند. برای افزودن نشانی اینترنتی به فهرست مجاز، با مدیر خود تماس بگیرید.

اشکال‌زدایی

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

ثبت وقایع

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

گزارش خطا

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

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

اعدام‌ها

اسکریپت برنامه‌های گوگل هر اجرا، از جمله گزارش‌های ابری را ثبت می‌کند. برای مشاهده اجراها، روی «اجراها کلیک کنید.

بررسی وضعیت سرویس

قطعی سرویس Google Workspace را در داشبورد وضعیت Google Workspace بررسی کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

دریافت کمک

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