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

สคริปต์ Google Ads มักจะต้องทำงานร่วมกับวันที่และเวลา กรณีใช้งานทั่วไป ได้แก่ การเรียกรายงานสำหรับช่วงวันที่ที่ต้องการ การกำหนดเวลาให้แคมเปญหรือกลุ่มโฆษณาทำงานในเวลาที่ต้องการ และการแสดงผลลัพธ์ในสเปรดชีตเวลาที่สคริปต์ทำงานครั้งล่าสุด คู่มือนี้จะอธิบายแนวคิดสำคัญ ข้อผิดพลาดที่พบบ่อย และวิธีที่แนะนำเมื่อทำงานกับวันที่และเวลาในสคริปต์ 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);

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

หากต้องการแสดงผลวันที่เป็นสตริงด้วยรูปแบบและเขตเวลาที่เฉพาะเจาะจง ให้ใช้ 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 เขตเวลาเริ่มต้นคืออเมริกา/Los_Angeles (เวลาแปซิฟิก) โดยไม่คำนึงถึงเขตเวลาที่เชื่อมโยงกับบัญชี 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());

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