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

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

הערה: באופן פנימי, 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\''));

בדוגמאות האלה ציינו את אזור הזמן ישירות באמצעות אזור זמן ID (מזהה). כדי לאחזר את אזור הזמן שמשויך לחשבון 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);

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

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

לאובייקטים של תאריכים ב-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, 2021 13:00:00 -0500');

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

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