רישום

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

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

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

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

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

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

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

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

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

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

הדוגמה הבאה ממחישה איך משתמשים בשירות 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. מסמנים את התיבה רישום חריגים שלא זוהו ב-Cloud Operations.

Error Reporting

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

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

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

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