רישום

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

ב-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 מספק גם גישה חלקית לשירות Cloud Logging ב-Google Cloud Platform (GCP). כשאתם צריכים רישום ביומן שיימשך כמה ימים, או אם צריכים פתרון מורכב יותר לרישום ביומן בסביבת ייצור עם משתמשים מרובים, כדאי להשתמש ב-Cloud Logging. מידע על שמירת נתונים ופרטים אחרים לגבי מכסות מופיעים במאמר מכסות ומגבלות ב-Cloud Logging.

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

שימוש ב-Cloud Logging

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

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

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

אפשר לרשום מחרוזות, מחרוזות מעוצבות ואפילו אובייקטים של 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 במסוף, בוחרים רשומה ביומן הרצויה ומרחיבים אותה כדי לצפות ב-metadata > labels > script.googleapis.com/user_key.

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

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

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

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

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

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

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

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

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

Error Reporting

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

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

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

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