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

סקריפטים של 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\''));

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

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

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(), שאילתת GAQL מחייבת לציין תאריכים בפורמט yyyy-MM-dd (לדוגמה, 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-Feb-21 בשעה 10:00:00.

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

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

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