کار با تاریخ و زمان

اسکریپت‌های گوگل ادز اغلب نیاز به کار با تاریخ و زمان دارند. موارد استفاده رایج شامل بازیابی گزارش‌ها برای یک محدوده تاریخی خاص، زمان‌بندی کمپین‌ها یا گروه‌های تبلیغاتی برای اجرا در زمان‌های خاص و خروجی دادن به یک صفحه گسترده در مورد آخرین زمان اجرای اسکریپت است. این راهنما مفاهیم مهم، مشکلات رایج و رویکردهای توصیه شده هنگام کار با تاریخ و زمان در اسکریپت‌های گوگل ادز را شرح می‌دهد.

مفاهیم پایه

برای کار با تاریخ و زمان در اسکریپت‌های گوگل ادز، از شیء تاریخ داخلی جاوا اسکریپت استفاده کنید. یک شیء تاریخ جاوا اسکریپت نشان‌دهنده یک لحظه خاص در زمان است. چندین روش برای ایجاد یک شیء تاریخ جدید وجود دارد:

// 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);

کاربران تازه‌کار اسکریپت‌ها اغلب در مورد نحوه‌ی مدیریت مناطق زمانی توسط اشیاء تاریخ دچار سردرگمی می‌شوند. یک روش طبیعی اما نادرست برای تصور یک شیء تاریخ، این است که آن را به عنوان زمان روی یک ساعت در یک منطقه‌ی زمانی واحد در نظر بگیریم. برای مثال، در قطعه کد قبل، برخی از کاربران به اشتباه فرض می‌کنند که date فقط در یک منطقه‌ی زمانی معتبر است، یعنی منطقه‌ی زمانی با انحراف -5 ساعت که برای ایجاد آن استفاده شده است. در این دیدگاه اشتباه، date برای استفاده در مناطق زمانی دیگر باید "تبدیل" شود.

در عوض، روش صحیح برای فکر کردن در مورد یک شیء تاریخ، در نظر گرفتن آن به عنوان یک لحظه خاص در زمان مستقل از هر منطقه زمانی است. اگرچه یک لحظه خاص در ساعت‌های مناطق زمانی مختلف به طور متفاوت نشان داده می‌شود، اما همان لحظه است. برای مثال، این قطعه کد را در نظر بگیرید:

// Create two date objects with different times and time zone 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);

نکته: جاوا اسکریپت به صورت داخلی یک شیء تاریخ را به صورت تعداد میلی‌ثانیه‌ها از اول ژانویه 1970 به وقت جهانی نشان می‌دهد.

از آنجایی که یک شیء تاریخ، لحظه خاصی از زمان را نشان می‌دهد، نیازی به "تبدیل" آن بین مناطق زمانی مختلف نیست. در عوض، می‌توان آن را به صورت رشته‌ای که برای یک منطقه زمانی خاص قالب‌بندی شده است، رندر کرد.

برای رندر کردن یک تاریخ به صورت رشته‌ای با فرمت و منطقه زمانی خاص، از 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 (زمان اقیانوس آرام) است. اگر می‌خواهید شیء تاریخ را به عنوان یک رشته با استفاده از یک قالب و منطقه زمانی سفارشی برای ثبت وقایع یا اهداف دیگر رندر کنید، همیشه Utilities.formatDate(date, timeZone, format) استفاده کنید.

منطقه زمانی پیش‌فرض هنگام ایجاد یک شیء تاریخ

هنگام ایجاد یک شیء تاریخ با استفاده از رشته‌ای که آفست منطقه زمانی را ارائه نمی‌دهد ، منطقه زمانی صرف نظر از منطقه زمانی مرتبط با حساب Google Ads، America/Los_Angeles (زمان اقیانوس آرام) فرض می‌شود. برای مثال:

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

// Mon Feb 17 13:00:00 GMT-08:00 2025
console.log(date);

هنگام ایجاد یک شیء تاریخ با استفاده از یک رشته، همیشه یک آفست منطقه زمانی را در نظر بگیرید تا مطمئن شوید که شیء تاریخ، لحظه مورد نظر شما را نشان می‌دهد.

منطقه زمانی پیش‌فرض در متدهای شیء تاریخ

اشیاء تاریخ جاوا اسکریپت چندین متد دارند که یک منطقه زمانی پیش‌فرض را در نظر می‌گیرند، مانند:

• getFullYear()
• getMonth()
• getDate()
• getDay()
• getHours()
• getMinutes()

این همچنین شامل معادل‌های set___() این متدها (برای مثال، setMonth() ) و getTimezoneOffset() می‌شود.

در اسکریپت‌های گوگل ادز، منطقه زمانی پیش‌فرض، صرف نظر از منطقه زمانی مرتبط با حساب گوگل ادز، آمریکا/لس‌آنجلس (زمان اقیانوس آرام) است. بنابراین، مگر اینکه حساب گوگل ادز شما در این منطقه زمانی باشد، معمولاً باید از استفاده از این روش‌ها خودداری کنید.

برای دریافت سال، ماه، تاریخ، روز، ساعت یا دقیقه برای یک شیء تاریخ در منطقه زمانی حساب کاربری خود، 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() روی یک شیء تاریخ، تعداد میلی‌ثانیه‌ها را از ابتدای ۱ ژانویه ۱۹۷۰ به وقت جهانی برمی‌گرداند. می‌توانید روی این مقدار محاسبات ریاضی انجام دهید، سپس مقدار جدید را با استفاده از setTime() روی یک شیء تاریخ اعمال کنید یا هنگام ایجاد یک شیء تاریخ جدید، آن را به عنوان پارامتر ارائه دهید.

برای مثال:

const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

در این مثال، yesterday دقیقاً ۲۴ ساعت پیش است.

گزارش‌دهی

هنگام بازیابی گزارش با استفاده از AdsApp.search() ، پرس و جوی GAQL نیاز دارد که تاریخ‌ها با فرمت yyyy-MM-dd مشخص شوند (برای مثال، 2025-06-30 معادل 30 ژوئن 2025 خواهد بود).

به همین ترتیب، متد getStatsFor() که در بسیاری از اشیاء اسکریپت‌های گوگل ادز موجود است، نیاز دارد که تاریخ‌ها با همین قالب مشخص شوند. برای قالب‌بندی یک شیء تاریخ با این قالب، 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'));

صفحات گسترده

اسکریپت‌های گوگل ادز اغلب خروجی را در یک صفحه گسترده، شامل اشیاء تاریخ، می‌نویسند. هنگام تنظیم یک سلول در یک صفحه گسترده با ارسال یک شیء تاریخ، از منطقه زمانی صفحه گسترده برای تفسیر آن تاریخ استفاده می‌شود. برای مثال، فرض کنید یک صفحه گسترده داریم که منطقه زمانی آن روی زمان اقیانوس آرام تنظیم شده است:

// Suppose today is February 17, 2025 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

مقدار موجود در سلول A1، ساعت 10:00:00 و تاریخ 17-Feb-25 خواهد بود.

برای اطمینان از اینکه اشیاء تاریخ همانطور که انتظار دارید در صفحه گسترده نوشته می‌شوند، منطقه زمانی صفحه گسترده را مطابق با منطقه زمانی حساب Google Ads خود تنظیم کنید:

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

همچنین می‌توانید زمان یک صفحه گسترده را به صورت دستی تنظیم کنید .