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

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

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

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

אזור הזמן שמוגדר כברירת מחדל הוא אמריקה/לוס אנג'לס (שעון החוף המערבי), ללא קשר לאזור הזמן שמשויך לחשבון 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___()) וגם את getTimezoneOffset().setMonth()

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

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

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

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

const date = new Date('February 17, 2025 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 (לדוגמה, 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-Feb-25 10:00:00.

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

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

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