עבודה עם תאריכים ושעות

לעתים קרובות, סקריפטים של 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);

משתמשים חדשים ב-Scripts מתקשים לפעמים להבין איך אובייקטים של תאריכים מטפלים באזורי זמן. דרך טבעית אבל שגויה לחשוב על אובייקט מסוג תאריך היא השעה בשעון באזור זמן יחיד. לדוגמה, בקטע הקוד שלמעלה, משתמשים מסוימים מניחים בטעות ש-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);

אזור הזמן שמוגדר כברירת מחדל הוא America/Los_Angeles (שעון האוקיינוס השקט), ללא קשר לאזור הזמן שמשויך לחשבון Google Ads. אם רוצים להציג את אובייקט התאריך כמחרוזת באמצעות פורמט וזמני שעון מותאמים אישית לצורכי רישום ביומן או למטרות אחרות, תמיד צריך להשתמש ב-Utilities.formatDate(date, timeZone, format).

אזור הזמן שמוגדר כברירת מחדל כשיוצרים אובייקט תאריך

כשיוצרים אובייקט תאריך באמצעות מחרוזת שלא כוללת שינוי שעון, ההנחה היא שתחום הזמן הוא America/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, אזור הזמן שמוגדר כברירת מחדל הוא America/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');

ה-constructor יכול לנתח רק פורמטים מסוימים של מחרוזות תאריך. כדי לוודא שניתוח מחרוזת התאריך יתבצע בצורה נכונה, תמיד צריך לספק אותה בפורמט MMMM dd, yyyy HH:mm:ss Z.

לדוגמה, כדי ליצור אובייקט תאריך לשעה 12:00 היום באזור הזמן של החשבון הנוכחי:

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(), צריך לציין את התאריכים בפורמט yyyy-MM-dd בשאילתת GAQL (לדוגמה, 2021-06-30 הוא 30 ביוני 2021).

באופן דומה, השיטה getStatsFor() שזמינה באובייקטים רבים של סקריפטים ב-Google Ads מחייבת לציין תאריכים באותו פורמט. משתמשים ב-Utilities.formatDate(date, timeZone, format) כדי לעצב אובייקט תאריך בפורמט הזה.

לדוגמה, כדי לאחזר דוח מיום אחד עד שלושה ימים לפני כן:

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 בפברואר 2021 10:00:00.

כדי לוודא שעצמים של תאריכים נכתבים בגיליון אלקטרוני כמצופה, צריך להגדיר את אזור הזמן של הגיליון האלקטרוני כך שיתאים לאזור הזמן של חשבון Google Ads:

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

אפשר גם להגדיר את השעה בגיליון האלקטרוני באופן ידני.