רישום

כשמפתחים אפליקציה מכל סוג, רצוי לרשום מידע כדי לעזור לאבחן תקלות במהלך הפיתוח, לזהות ולאבחן בעיות של לקוחות, ולמטרות אחרות.

ב-Apps Script יש שלושה מנגנונים שונים לרישום ביומן:

  • יומן הביצוע של Apps Script המובנה. היומן הזה קל ופשוט ומשודר בזמן אמת, אבל הוא נשמר רק למשך זמן קצר.

  • ממשק Cloud Logging ב Developer Console, שמספק יומנים שנשארים לאורך ימים רבים לאחר במהלך היצירה.

  • הממשק Error Reporting ב-Developer Console, שאוסף ומתעד שגיאות שמתרחשות בזמן שהסקריפט פועל.

הנושאים האלה מתוארים בסעיפים הבאים. נוסף למנגנונים האלה, תוכלו גם ליצור קוד יומן משלכם שכותב, למשל, מידע לגיליון אלקטרוני של רישום ביומן או במסד הנתונים של JDBC.

שימוש ביומן הביצוע של Apps Script

גישה בסיסית להתחברות ב-Apps Script היא להשתמש יומן ביצוע. כדי לצפות ביומנים האלה, בעורך, לוחצים על יומן ביצוע. כשמריצים פונקציה או משתמשים לניפוי באגים, היומנים עוברים בסטרימינג בזמן אמת.

אפשר להשתמש ב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);
  try {
    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);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed with error %s', err.message);
  }
}

כשהסקריפט הזה רץ עם ערכי הקלט '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

Cloud Logging

Apps Script מספק גם גישה חלקית ל-Google Cloud Platform (GCP) שירות Cloud Logging. אחרי ש נדרשת רישום ביומן שיימשך כמה ימים או צורך ברישום מורכב יותר ביומן לסביבת ייצור מרובת משתמשים, Cloud Logging הוא המועדף בחירה. מידע נוסף על המכסות והמגבלות של Cloud Logging לקבלת מידע על שמירת נתונים ומכסות אחרות.

אם אתם זקוקים להגדלת מכסת הרישום ביומן, אפשר שולחים בקשה למכסה ב-Google Cloud Platform. לשם כך נדרשת גישה אל פרויקט ב-Cloud Platform שבהם הסקריפט משתמש.

שימוש ב-Cloud Logging

יומני Cloud מצורפים אל הפרויקט ב-Google Cloud המשויך ל-Apps Script שלך. אפשר לראות גרסה פשוטה יותר של הנושאים האלה יומנים במרכז הבקרה של Apps Script.

כדי להשתמש ב-Cloud Logging באופן מלא וביכולות שלו, צריך להשתמש פרויקט רגיל ב-Google Cloud בפרויקט הסקריפט שלכם. כך תוכלו לגשת ליומני Cloud ישירות מסוף GCP ומעניק לכם יותר אפשרויות הצגה וסינון.

במהלך הרישום ביומן, מומלץ להימנע מתיעוד של מידע אישי מידע על המשתמש, כמו כתובות אימייל. יומני הענן מתויג באופן אוטומטי עם מפתחות משתמשים פעילים שבה אפשר להשתמש כדי לאתר הודעות יומן של משתמש ספציפי במקרה הצורך.

אפשר לרשום ביומן מחרוזות, מחרוזות מעוצבות ואפילו אובייקטים של JSON באמצעות הפונקציות שסופקו על ידי Apps Script שירות console.

הדוגמה הבאה מראה איך להשתמש ב-console שירות לרישום מידע ב-Cloud Operations.

utils/logging.gs
/**
 * 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 במסוף, בוחרים רשומה שיש בה עניין ביומן ומרחיבים אותה כדי להציג אותה. מטא-נתונים > תוויות > script.googleapis.com/user_key.

אפשר גם לקבל את המפתח הזמני למשתמש הפעיל בהתקשרות Session.getTemporaryActiveUserKey() בתסריט שלכם. אחת מהדרכים להשתמש בשיטה הזו היא להציג את המפתח למשתמש. בזמן שהם מריצים את הסקריפט. לאחר מכן המשתמשים יוכלו לכלול את המפתחות שלהם בזמן הדיווח על בעיות, כדי לעזור לכם לזהות את היומנים הרלוונטיים.

רישום ביומן של חריגים

רישום ביומן של חריגים שולח חריגים לא מטופלים בקוד פרויקט הסקריפט ל-Cloud Logging, יחד עם דוח קריסות.

כדי להציג יומני חריגים, פועלים לפי השלבים הבאים:

  1. פותחים את פרויקט Apps Script.
  2. בצד ימין, לוחצים על הפעלות .
  3. למעלה, לוחצים על הוספת מסנן > סטטוס.
  4. מסמנים את התיבות נכשל ותם הזמן הקצוב לתפוגה.

יש לך גם אפשרות להציג חריגים שנרשמו במסוף GCP אם בפרויקט הסקריפט שלכם נעשה שימוש פרויקט רגיל ב-Google Cloud שיש לכם גישה אליהם.

הפעלת רישום חריגים ביומן

רישום ביומן של חריגים מופעל כברירת מחדל בפרויקטים חדשים. כדי להפעיל חריג רישום ביומן של פרויקטים ישנים יותר, מבצעים את הפעולות הבאות:

  1. פותחים את פרויקט הסקריפט.
  2. בצד ימין, לוחצים על הגדרות הפרויקט .
  3. מסמנים את תיבת הסימון Log uncaught issues to Cloud Operations.

Error Reporting

רישום ביומן של חריגים משתלב באופן אוטומטי עם Cloud Error Reporting, שירות שצובר ומציג את השגיאות שהופקו בסקריפט שלכם. אפשר להציג את דוחות השגיאות של Cloud במסוף Google Cloud. אם מופיעה ההודעה "הגדרת דיווח על שגיאות" זה בגלל הסקריפט שלך עדיין לא תיעד אף חריג. לא נדרשת הגדרה מעבר לזה הפעלת הרישום ביומן החריגים

דרישות רישום ביומן

אין דרישות לשימוש ביומן הביצוע המובנה.

אפשר לצפות בגרסה פשוטה יותר של יומני Cloud בקטע מרכז הבקרה של Apps Script. אבל, כדי להפיק את המקסימום מ-Cloud Logging ומדיווח שגיאות שנדרשים לכם כדי לגשת אליהם. לפרויקט GCP של הסקריפט. זה אפשרי רק אם פרויקט הסקריפט שלך משתמש בפרויקט רגיל ב-Google Cloud.