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

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

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

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

// 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, 2021 13:00:00 -0500');

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

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

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

// Create two date objects with different times and timezone offsets.
const date1 = new Date('February 17, 2021 13:00:00 -0500');
const date2 = new Date('February 17, 2021 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 ออบเจ็กต์วันที่จะแสดงเป็นจํานวนมิลลิวินาทีนับตั้งแต่วันที่ 1 มกราคม 1970 (UTC)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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" ในการสร้างสตริงวันที่ที่จะส่งไปยังตัวสร้างวันที่ เนื่องจากตัวสร้างจะไม่สามารถแยกวิเคราะห์สตริงวันที่ได้ ใช้รูปแบบ "Z" เท่านั้น

คณิตศาสตร์วันที่

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

เช่น

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 (เช่น 2021-06-30 หมายถึงวันที่ 30 มิถุนายน 2021)

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

เช่น หากต้องการเรียกข้อมูลรายงานจาก 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 มักจะเขียนเอาต์พุตลงในสเปรดชีต ซึ่งรวมถึงออบเจ็กต์วันที่ เมื่อตั้งค่าเซลล์ในสเปรดชีตโดยการส่งออบเจ็กต์วันที่ ระบบจะใช้เขตเวลาของสเปรดชีตเพื่อตีความวันที่ดังกล่าว ตัวอย่างเช่น สมมติว่าเรามีสเปรดชีตที่ตั้งค่าเขตเวลาเป็นเวลาแปซิฟิก

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

ค่าใน A1 จะเป็น 17-Feb-21 10:00:00

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

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

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