רישום

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

ב-Apps Script יש שלושה מנגנונים שונים לתיעוד ביומן:

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

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

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

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

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

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

אפשר להשתמש בשירותי הרישום ביומן של Logger או של console ביומן הביצועים המובנה.

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

לדוגמה, נניח את הפונקציה הבאה:

/**
 * 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 באמצעות הפונקציות ששירות console של Apps Script מספק.

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

/**
 * 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 בלי לחשוף את הזהויות שלהם. המפתחות הם לכל סקריפט, והם משתנים בערך פעם בחודש כדי לספק אבטחה נוספת במקרה שמשתמש חושף את הזהות שלו למפתח, למשל בזמן דיווח על בעיה.

מפתחות זמניים של משתמשים פעילים עדיפים על מזהי רישום ביומן כמו כתובות אימייל, כי:

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

כדי למצוא מפתחות משתמשים פעילים זמניים ברשאות ביומן Cloud, מציגים את יומני Cloud במסוף Google Cloud. אפשר לעשות זאת רק אם בפרויקט הסקריפט נעשה שימוש בפרויקט רגיל ב-Google Cloud שיש לכם גישה אליו. אחרי שפותחים את הפרויקט ב-Google Cloud במסוף, בוחרים רשומה ביומן שמעניינת אתכם ומרחיבים אותה כדי להציג את metadata > labels > script.googleapis.com/user_key.

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

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

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

כדי להציג יומני חריגות:

1. פותחים את הפרויקט ב-Apps Script.
2. בצד ימין, לוחצים על הפעלות playlist_play.
3. בחלק העליון, לוחצים על הוספת מסנן > סטטוס.
4. מסמנים את התיבות Failed ו-Timed out.

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

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

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

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

Error Reporting

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

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

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

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