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

לעתים קרובות, סקריפטים של 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, 2025 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, 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, אובייקט תאריך מיוצג כמספר המילי-שניות מאז 1 בינואר 1970 (UTC).

מאחר שאובייקט תאריך מייצג רגע מסוים בזמן, אין צורך "להמיר" אותו בין אזורי זמן. במקום זאת, אפשר להציג אותו כמחרוזת בפורמט של אזור זמן מסוים.

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

בדוגמאות האלה צוין אזור הזמן ישירות באמצעות מזהה של אזור זמן. כדי לאחזר את אזור הזמן שמשויך לחשבון Google Ads שבו פועל הסקריפט, משתמשים ב-AdsApp.currentAccount().getTimeZone().

מלכודות נפוצות

ריכזנו כאן כמה מלכודות נפוצות שקשורות לתאריכים.

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

כשרושמים ישירות אובייקט תאריך באמצעות 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. אם רוצים להציג את אובייקט התאריך כמחרוזת באמצעות פורמט וזמני שעון מותאמים אישית לצורכי רישום ביומן או למטרות אחרות, תמיד צריך להשתמש ב-Utilities.formatDate(date, timeZone, format).

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

כשיוצרים אובייקט תאריך באמצעות מחרוזת שלא כוללת שינוי שעון, ההנחה היא שתחום הזמן הוא America/Los_Angeles (שעון החוף המערבי), ללא קשר לתחום הזמן שמשויך לחשבון Google Ads. לדוגמה:

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

// Mon Feb 17 13:00:00 GMT-08:00 2025
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() כדי לקבל את אזור הזמן של החשבון.

יצירת אובייקט תאריך מחרוזת תאריך בפורמט

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

const date = new Date('February 17, 2025 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 (לדוגמה, 2025-06-30 הוא 30 ביוני 2025).

באופן דומה, השיטה 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, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

הערך ב-A1 יהיה 17 בפברואר 2025 בשעה 10:00:00.

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

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

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