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

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

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

ใช้วันที่ในตัวของ JavaScript เพื่อทำงานกับวันที่และเวลาในสคริปต์ Google Ads ออบเจ็กต์ ออบเจ็กต์วันที่ของ 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\''));

ตัวอย่างเหล่านี้ระบุเขตเวลาโดยตรงโดยใช้เขตเวลา รหัส หากต้องการเรียกข้อมูล เขตเวลาที่เชื่อมโยงกับบัญชี 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-กุมภาพันธ์ 21 เวลา 10:00:00

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

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

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