רישום ביומן

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

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

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

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

• ממשק דיווח השגיאות ב-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}`);
  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);
}

כשמריצים את הסקריפט הזה עם הקלט '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.

/**
 * A placeholder function to be timed.
 * @param {Object} parameters
 */
function myFunction(parameters) {
  // Placeholder for the function being timed.
}

/**
 * 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. מסמנים את תיבות הסימון נכשל ופג הזמן הקצוב לתגובה.

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

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

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

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

Error Reporting

רישום חריגים ביומן משתלב אוטומטית עם Cloud Error Reporting, שירות שמצבר ומציג שגיאות שנוצרות בסקריפט. אפשר לראות את דוחות השגיאות ב-Cloud במסוף Google Cloud. אתם לא צריכים להגדיר ידנית את דיווח השגיאות או ליצור רשומות מעקב. ‫Apps Script מאכלס באופן אוטומטי את השדות הנדרשים כשמופעלת חריגה או כשמשתמשים ב-console.error() עם אובייקט Error. אם מוצגת ההודעה 'הגדרת דיווח על שגיאות', הסיבה לכך היא שעדיין לא נרשמו חריגים בסקריפט. לא נדרשת הגדרה מעבר להפעלת רישום חריגים ביומן.

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

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

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