Logging

เมื่อพัฒนาแอปทุกประเภท คุณมักจะต้องบันทึกข้อมูลเพื่อช่วยในการวินิจฉัยข้อบกพร่องระหว่างการพัฒนา เพื่อระบุและวินิจฉัยปัญหาของลูกค้า และเพื่อวัตถุประสงค์อื่นๆ

Apps Script มีกลไกการบันทึก 3 รูปแบบดังนี้

• บันทึกการดำเนินการของ Apps Script ในตัว บันทึกนี้เบาและมีการสตรีมแบบเรียลไทม์ แต่จะอยู่ได้เพียงระยะเวลาสั้นๆ

• อินเทอร์เฟซการบันทึกในระบบคลาวด์ในคอนโซลของนักพัฒนาซอฟต์แวร์ ซึ่งแสดงบันทึกที่เก็บไว้เป็นเวลาหลายวันหลังจากสร้าง

• อินเทอร์เฟซการรายงานข้อผิดพลาดในคอนโซลนักพัฒนาซอฟต์แวร์ ซึ่งจะรวบรวมและบันทึกข้อผิดพลาดที่เกิดขึ้นขณะที่สคริปต์ทำงาน

ซึ่งจะอธิบายในส่วนต่อไปนี้ นอกจากกลไกเหล่านี้แล้ว คุณยังสร้างโค้ดบันทึกของคุณเองได้ด้วย เช่น เขียนข้อมูลลงในสเปรดชีตหรือการบันทึกฐานข้อมูล JDBC

ใช้บันทึกการดำเนินการของ Apps Script

แนวทางพื้นฐานในการเข้าสู่ระบบ Apps Script คือการใช้บันทึกการดำเนินการในตัว หากต้องการดูบันทึกเหล่านี้ ให้คลิกบันทึกการดำเนินการที่ด้านบนของเครื่องมือแก้ไข เมื่อคุณเรียกใช้ฟังก์ชันหรือใช้โปรแกรมแก้ไขข้อบกพร่อง ระบบจะสตรีมบันทึกแบบเรียลไทม์

คุณสามารถใช้บริการบันทึกของ Logger หรือ console ในบันทึกการดำเนินการในตัว

บันทึกเหล่านี้มีไว้สําหรับการตรวจสอบแบบง่ายระหว่างการพัฒนาและการแก้ไขข้อบกพร่อง และจะไม่คงอยู่นาน

เช่น ลองดูฟังก์ชันนี้

utils/logging.gs

ดูใน GitHub

/**
 * 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" และ "[e-mail]" ระบบจะเขียนบันทึกต่อไปนี้

[16-09-12 13:50:42:193 PDT] ส่งอีเมลข้อมูลแถวที่ 2 ไปยัง [e-mail]
[16-09-12 13:50:42:271 PDT] ข้อมูลแถวที่ 2: ค่าจัดส่ง 103.24

Cloud Logging

นอกจากนี้ Apps Script ยังให้สิทธิ์เข้าถึงบริการ Cloud Logging ของ Google Cloud Platform (GCP) บางส่วนด้วย เมื่อต้องการการบันทึกที่เก็บไว้เป็นเวลาหลายวัน หรือต้องการโซลูชันการบันทึกที่ซับซ้อนมากขึ้นสําหรับสภาพแวดล้อมเวอร์ชันที่ใช้งานจริงที่มีผู้ใช้หลายคน คุณควรเลือกใช้การบันทึกในระบบคลาวด์ ดูรายละเอียดการเก็บรักษาข้อมูลและโควต้าอื่นๆ ได้ที่โควต้าและขีดจํากัดการบันทึกในระบบคลาวด์

หากต้องการโควต้าการบันทึกเพิ่มเติม คุณสามารถส่งคำขอโควต้า Google Cloud Platform ซึ่งคุณต้องมีสิทธิ์เข้าถึงโปรเจ็กต์ Cloud Platform ที่ใช้สคริปต์

หมายเหตุ: การบันทึกในระบบคลาวด์ให้บริการหลายอย่างนอกเหนือจากการจัดเก็บบันทึก เช่น การแจ้งเตือนและเมตริก ขณะนี้บริการเหล่านี้ยังไม่พร้อมใช้งานจาก Apps Script

การใช้ Cloud Logging

บันทึกในระบบคลาวด์จะแนบอยู่กับโปรเจ็กต์ Google Cloud ที่เชื่อมโยงกับ Apps Script คุณดูบันทึกเหล่านี้ในเวอร์ชันที่เรียบง่ายได้ในหน้าแดชบอร์ด Apps Script

หากต้องการใช้ Cloud Logging และความสามารถของเครื่องมือนี้อย่างเต็มรูปแบบ ให้ใช้โปรเจ็กต์ Google Cloud มาตรฐานกับโปรเจ็กต์สคริปต์ ซึ่งจะช่วยให้คุณเข้าถึงบันทึกในระบบคลาวด์ได้โดยตรงในคอนโซล GCP และจะมีตัวเลือกการดูและกรองเพิ่มเติม

หมายเหตุ: หากคุณใช้รันไทม์ Rhino การบันทึกในระบบคลาวด์จะไม่รองรับบริการ Apps Script Logger แต่ให้ใช้ console service

แทน

เมื่อบันทึก แนวทางปฏิบัติด้านความเป็นส่วนตัวที่ดีคือหลีกเลี่ยงการบันทึกข้อมูลส่วนบุคคลเกี่ยวกับผู้ใช้ เช่น อีเมล ระบบจะติดป้ายกำกับบันทึกในระบบคลาวด์โดยอัตโนมัติด้วยคีย์ผู้ใช้ที่ใช้งานอยู่ ซึ่งคุณใช้เพื่อค้นหาข้อความบันทึกของผู้ใช้ที่เฉพาะเจาะจงได้เมื่อจำเป็น

คุณสามารถบันทึกสตริง สตริงที่มีการจัดรูปแบบ และแม้แต่ออบเจ็กต์ JSON ได้โดยใช้ฟังก์ชันที่บริการ Apps Scriptconsole มีให้

ตัวอย่างต่อไปนี้แสดงวิธีใช้บริการ console เพื่อบันทึกข้อมูลใน Cloud Operations

utils/logging.gs

ดูใน GitHub

/**
 * 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 ในคอนโซลแล้ว ให้เลือกรายการบันทึกที่สนใจและขยายเพื่อดูข้อมูลเมตา > ป้ายกำกับ > script.googleapis.com/user_key

นอกจากนี้ คุณยังรับคีย์ผู้ใช้ที่ใช้งานอยู่ชั่วคราวได้โดยเรียกใช้ Session.getTemporaryActiveUserKey() ในสคริปต์ วิธีหนึ่งในการใช้เมธอดนี้คือการแสดงคีย์ให้ผู้ใช้เห็นขณะที่ผู้ใช้เรียกใช้สคริปต์ จากนั้นผู้ใช้สามารถเลือกที่จะใส่คีย์ของตนเมื่อรายงานปัญหาเพื่อช่วยให้คุณระบุบันทึกที่เกี่ยวข้องได้

การบันทึกข้อยกเว้น

การบันทึกข้อยกเว้นจะส่งข้อยกเว้นที่ไม่ได้รับการจัดการในโค้ดโปรเจ็กต์สคริปต์ไปยังการบันทึกของ Cloud พร้อมด้วยสแต็กเทรซ

หากต้องการดูบันทึกข้อยกเว้น ให้ทำตามขั้นตอนด้านล่าง

1. เปิดโปรเจ็กต์ Apps Script
2. คลิกการเรียกใช้ ทางด้านซ้าย
3. ที่ด้านบน ให้คลิกเพิ่มตัวกรอง > สถานะ
4. เลือกช่องทําเครื่องหมายไม่สําเร็จและหมดเวลา

นอกจากนี้ คุณยังดูข้อยกเว้นที่บันทึกไว้ในคอนโซล GCP ได้หากโปรเจ็กต์สคริปต์ใช้โปรเจ็กต์ Google Cloud มาตรฐานที่คุณมีสิทธิ์เข้าถึง

เปิดใช้การบันทึกข้อยกเว้น

การบันทึกข้อยกเว้นจะเปิดอยู่โดยค่าเริ่มต้นสําหรับโปรเจ็กต์ใหม่ หากต้องการเปิดใช้การบันทึกข้อยกเว้นสําหรับโปรเจ็กต์เก่า ให้ทําตามขั้นตอนด้านล่าง

1. เปิดโปรเจ็กต์สคริปต์
2. คลิกการตั้งค่าโปรเจ็กต์ ทางด้านซ้าย
3. เลือกช่องทําเครื่องหมายบันทึกข้อยกเว้นที่ตรวจไม่พบไปยัง Cloud Operations

Error Reporting

การบันทึกข้อยกเว้นจะผสานรวมกับ Cloud Error Reporting โดยอัตโนมัติ ซึ่งเป็นบริการที่รวบรวมและแสดงข้อผิดพลาดที่เกิดขึ้นในสคริปต์ คุณสามารถดูรายงานข้อผิดพลาดใน Cloud ในคอนโซล Google Cloud หากได้รับข้อความแจ้งให้ "ตั้งค่าการรายงานข้อผิดพลาด" แสดงว่าสคริปต์ของคุณยังไม่ได้บันทึกข้อยกเว้นใดๆ ไม่จำเป็นต้องตั้งค่าเพิ่มเติมนอกเหนือจากการเปิดใช้การบันทึกข้อยกเว้น

ข้อกำหนดในการบันทึก

การใช้บันทึกการดำเนินการในตัวนั้นไม่มีข้อกำหนด

คุณดูบันทึก Cloud เวอร์ชันที่เข้าใจง่ายได้ในหน้าแดชบอร์ด Apps Script อย่างไรก็ตาม หากต้องการใช้การบันทึกในระบบคลาวด์และการรายงานข้อผิดพลาดให้ได้ประโยชน์สูงสุด คุณต้องมีสิทธิ์เข้าถึงโปรเจ็กต์ GCP ของสคริปต์ ซึ่งทำได้ก็ต่อเมื่อโปรเจ็กต์สคริปต์ใช้โปรเจ็กต์ Google Cloud มาตรฐาน