การทํางานกับวันที่และเวลา

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

แนวคิดพื้นฐาน

หากต้องการทำงานกับวันที่และเวลาในสคริปต์ Google Ads ให้ใช้ออบเจ็กต์ Date ในตัวของ JavaScript ออบเจ็กต์ Date ของ JavaScript แสดงถึงช่วงเวลาหนึ่งๆ คุณสร้างออบเจ็กต์ Date ใหม่ได้หลายวิธี ดังนี้

// Create a date object for the current date and time.
const now = new Date();

// Create a date object for a past date and time using a formatted string.
const date = new Date('February 17, 2025 13:00:00 -0500');

// Create a copy of an existing date object.
let copy = new Date(date);

ผู้ใช้สคริปต์ใหม่ๆ มักสับสนเกี่ยวกับวิธีที่ออบเจ็กต์ Date จัดการเขตเวลา วิธีคิดที่ดูสมเหตุสมผลแต่ไม่ถูกต้อง เกี่ยวกับออบเจ็กต์ Date คือ เวลาบนนาฬิกาในเขตเวลาเดียว ตัวอย่างเช่น ในข้อมูลโค้ดก่อนหน้านี้ ผู้ใช้บางรายเข้าใจผิดว่า date ใช้ได้เฉพาะในเขตเวลาเดียว นั่นคือเขตเวลาที่มีออฟเซ็ต -5 ชั่วโมงซึ่งใช้สร้างออบเจ็กต์ ในมุมมองที่ผิดพลาดนั้น date จะต้อง "แปลง" เพื่อให้ใช้ในเขตเวลาอื่นๆ ได้

แต่วิธีที่ถูกต้อง ในการคิดเกี่ยวกับออบเจ็กต์ Date คือการคิดว่าเป็นช่วงเวลาหนึ่งๆ ที่ไม่ขึ้นอยู่กับเขตเวลาใดๆ แม้ว่าช่วงเวลาหนึ่งๆ จะแสดงบนนาฬิกาในเขตเวลาต่างๆ กัน แต่ก็เป็นช่วงเวลาเดียวกัน ตัวอย่างเช่น ลองดูข้อมูลโค้ดนี้

// Create two date objects with different times and time zone offsets.
const date1 = new Date('February 17, 2025 13:00:00 -0500');
const date2 = new Date('February 17, 2025 10:00:00 -0800');

// getTime() returns the number of milliseconds since the beginning of
// January 1, 1970 UTC.
// True, as the dates represent the same moment in time.
console.log(date1.getTime() == date2.getTime());

// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
console.log(date1 == date2);

หมายเหตุ: ภายใน JavaScript จะแสดงออบเจ็กต์ Date เป็นจำนวน มิลลิวินาทีตั้งแต่ 1 มกราคม 1970 UTC

เนื่องจากออบเจ็กต์ Date แสดงถึงช่วงเวลาหนึ่งๆ จึงไม่จำเป็นต้อง "แปลง" ระหว่างเขตเวลา แต่สามารถแสดงเป็นสตริงที่ จัดรูปแบบสำหรับเขตเวลาหนึ่งๆ ได้

หากต้องการแสดงวันที่เป็นสตริงที่มีรูปแบบและเขตเวลาที่เฉพาะเจาะจง ให้ใช้ Utilities.formatDate(date, timeZone, format) เช่น

const date = new Date('February 17, 2025 13:00:00 -0500');

// February 17, 2025 13:00:00 -0500
console.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2025 10:00:00 -0800
console.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2025-02-17T18:00:00.000Z
console.log(Utilities.formatDate(date, 'Etc/GMT', 'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\''));

ตัวอย่างเหล่านี้ระบุเขตเวลาโดยตรงโดยใช้a รหัสเขตเวลา หากต้องการดึงข้อมูลเขตเวลาที่เชื่อมโยงกับบัญชี Google Ads ที่เรียกใช้ สคริปต์ ให้ใช้ AdsApp.currentAccount().getTimeZone()

ข้อผิดพลาดที่พบบ่อย

ต่อไปนี้คือข้อผิดพลาดที่พบบ่อยเกี่ยวกับวันที่

เขตเวลาเริ่มต้นเมื่อบันทึกออบเจ็กต์ Date

เมื่อบันทึกออบเจ็กต์ Date โดยตรงโดยใช้ Logger.log() ระบบจะแสดงออบเจ็กต์โดยใช้รูปแบบและเขตเวลาเริ่มต้น เช่น

const date = new Date('February 17, 2025 13:00:00 -0500');

// Mon Feb 17 10:00:00 GMT-08:00 2025
console.log(date);

เขตเวลาเริ่มต้นคือ America/Los_Angeles (เวลาแปซิฟิก) ไม่ว่า เขตเวลาที่เชื่อมโยงกับบัญชี Google Ads จะเป็นเขตเวลาใดก็ตาม หากต้องการแสดง ออบเจ็กต์ Date เป็นสตริงโดยใช้รูปแบบและเขตเวลาที่กำหนดเองสำหรับการบันทึกหรือ วัตถุประสงค์อื่นๆ ให้ใช้ Utilities.formatDate(date, timeZone, format) เสมอ

เขตเวลาเริ่มต้นเมื่อสร้างออบเจ็กต์ Date

เมื่อสร้างออบเจ็กต์ Date โดยใช้สตริงที่ ไม่ได้ระบุออฟเซ็ตเขตเวลา ระบบจะถือว่าเขตเวลาคือ America/Los_Angeles (เวลาแปซิฟิก) ไม่ว่าเขตเวลาที่เชื่อมโยงกับบัญชี Google Ads จะเป็นเขตเวลาใดก็ตาม เช่น

// Create a date without specifying the time zone offset.
const date = new Date('February 17, 2025 13:00:00');

// Mon Feb 17 13:00:00 GMT-08:00 2025
console.log(date);

เมื่อสร้างออบเจ็กต์ Date โดยใช้สตริง ให้ระบุออฟเซ็ตเขตเวลาเสมอเพื่อให้แน่ใจว่าออบเจ็กต์ Date แสดงถึงช่วงเวลาที่คุณต้องการจริงๆ

เขตเวลาเริ่มต้นในเมธอดออบเจ็กต์ Date

ออบเจ็กต์ Date ของ JavaScript มีเมธอดหลายรายการที่ใช้เขตเวลาเริ่มต้น เช่น

• getFullYear()
• getMonth()
• getDate()
• getDay()
• getHours()
• getMinutes()

ซึ่งรวมถึงเมธอด set___() ที่เทียบเท่าของเมธอดเหล่านี้ (เช่น setMonth()) และ getTimezoneOffset()

ในสคริปต์ Google Ads เขตเวลาเริ่มต้นคือ America/Los_Angeles (เวลาแปซิฟิก ) ไม่ว่าเขตเวลาที่เชื่อมโยงกับบัญชี Google Ads จะเป็นเขตเวลาใดก็ตาม ดังนั้น คุณควรหลีกเลี่ยงการใช้เมธอดเหล่านี้โดยทั่วไป เว้นแต่บัญชี Google Ads ของคุณจะอยู่ในเขตเวลานี้

หากต้องการรับปี เดือน วันที่ วัน ชั่วโมง หรือนาทีสำหรับออบเจ็กต์ Date ใน เขตเวลาของบัญชี ให้ใช้ Utilities.formatDate(date, timeZone, format) ที่มีรูปแบบที่ระบุส่วนของวันที่หรือเวลาที่ต้องการ และใช้ AdsApp.currentAccount().getTimeZone() เพื่อรับเขตเวลาของบัญชี

การสร้างออบเจ็กต์ Date จากสตริงวันที่ที่จัดรูปแบบ

คุณสร้างออบเจ็กต์ Date ได้โดยส่งสตริงวันที่ที่จัดรูปแบบไปยังตัวสร้าง Date เช่น

const date = new Date('February 17, 2025 13:00:00 -0500');

ตัวสร้างจะแยกวิเคราะห์ได้เฉพาะรูปแบบสตริงวันที่บางรูปแบบเท่านั้น โปรดระบุสตริงวันที่ในรูปแบบ MMMM dd, yyyy HH:mm:ss Z เสมอเพื่อให้แน่ใจว่าระบบจะแยกวิเคราะห์สตริงวันที่ ได้อย่างถูกต้อง

ตัวอย่างเช่น หากต้องการสร้างออบเจ็กต์ Date สำหรับเที่ยงวันนี้ในเขตเวลาของบัญชีปัจจุบัน ให้ทำดังนี้

const now = new Date();
const timeZone = AdsApp.currentAccount().getTimeZone();
const noonString = Utilities.formatDate(now, timeZone, 'MMMM dd, yyyy 12:00:00 Z');
const noon = new Date(noonString);

อย่าใช้รูปแบบ "z" เพื่อสร้างสตริงวันที่ที่จะส่งไปยังตัวสร้าง Date เนื่องจากตัวสร้างอาจแยกวิเคราะห์สตริงดังกล่าวไม่ได้เสมอไป ให้ใช้รูปแบบ "Z" เท่านั้น

การคำนวณวันที่

สคริปต์บางรายการต้องทำการคำนวณวันที่อย่างง่าย เช่น การหาวันที่ก่อนหรือหลังวันที่ที่กำหนด X วัน เมื่อทำการคำนวณวันที่ ให้ใช้ getTime() การเรียก getTime() ในออบเจ็กต์ Date จะแสดงจำนวนมิลลิวินาทีตั้งแต่ต้นเดือนมกราคม 1970 UTC คุณสามารถทำการคำนวณค่านี้ จากนั้นใช้ค่าใหม่กับออบเจ็กต์ Date โดยใช้ setTime() หรือระบุค่าดังกล่าวเป็นพารามิเตอร์เมื่อสร้างออบเจ็กต์ Date ใหม่

เช่น

const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

ในตัวอย่างนี้ yesterday คือเมื่อ 24 ชั่วโมงที่แล้ว

การรายงาน

เมื่อดึงข้อมูลรายงานโดยใช้ AdsApp.search(), การค้นหา GAQL กำหนดให้ระบุวันที่ในรูปแบบ yyyy-MM-dd (เช่น 2025-06-30 จะเป็นวันที่ 30 มิถุนายน 2025)

เช่นเดียวกัน เมธอด getStatsFor() ที่มีอยู่ในออบเจ็กต์สคริปต์ Google Ads หลายรายการกำหนดให้ระบุวันที่ในรูปแบบเดียวกัน ใช้ Utilities.formatDate(date, timeZone, format) เพื่อจัดรูปแบบออบเจ็กต์ Date ในรูปแบบนี้

ตัวอย่างเช่น หากต้องการดึงข้อมูลรายงานจาก 1 ถึง 3 วันที่ผ่านมา ให้ทำดังนี้

const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
const to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);

const timeZone = AdsApp.currentAccount().getTimeZone();
const results = AdsApp.search(
    'SELECT campaign.name, metrics.clicks' +
    'FROM campaign ' +
    'WHERE segments.date BETWEEN ' +
    Utilities.formatDate(from, timeZone, 'yyyy-MM-dd') + ' AND ' +
    Utilities.formatDate(to, timeZone, 'yyyy-MM-dd'));

สเปรดชีต

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

// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

ค่าใน A1 จะเป็น 17-ก.พ.-25 10:00:00

หากต้องการให้แน่ใจว่าระบบจะเขียนออบเจ็กต์ Date ลงในสเปรดชีตตามที่คุณต้องการ ให้ตั้งค่าเขตเวลาของสเปรดชีตให้ตรงกับเขตเวลาของบัญชี Google Ads โดยทำดังนี้

spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());

นอกจากนี้ คุณยังตั้งเวลาของสเปรดชีตด้วยตนเองได้ด้วย