عیب یابی

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

پیام های خطا

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

خطاهای نحوی

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

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

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

وجود ندارد) پس از فهرست آرگومان. (خط 4)

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

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

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

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" را برای آدرس ایمیل ارسال می کنیم. از آنجایی که این یک آدرس ایمیل معتبر نیست، هنگام اجرای اسکریپت خطای زیر رخ می دهد:

ایمیل نامعتبر: جان (خط 5)

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

خطاهای رایج

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

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

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

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

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

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

برای انجام آن عمل مجوز لازم است.

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

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

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

1. در سمت چپ پروژه Apps Script، روی Triggers alarm کلیک کنید.
2. در سمت راست ماشه ای که می خواهید حذف کنید، روی More more_vert > حذف محرک کلیک کنید.

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

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

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

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

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

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

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

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

کتابخانه گم شده است

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

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

خطا به دلیل از دست رفتن نسخه کتابخانه یا نسخه استقرار رخ داده است. کد خطا Not_Found

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

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

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

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

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

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

تماس‌های UrlFetch به <URL> توسط سرپرست شما مجاز نیست

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

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

اشکال زدایی

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

ورود به سیستم

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

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

گزارش خطا

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

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

اعدام ها

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

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

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

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

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

از دیباگر و نقاط شکست استفاده کنید

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

نقطه شکست اضافه کنید

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

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

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

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

برای کنترل نحوه اجرای اسکریپت، در بالای پانل Debugger، از دکمه های "Step in"، "Step over" و "Step out" استفاده کنید. اینها به شما امکان می دهند اسکریپت را یک خط در یک زمان اجرا کنید و بررسی کنید که چگونه مقادیر در طول زمان تغییر می کنند.

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

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

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

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

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

کمک گرفتن

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