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

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

مفاهیم پایه

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

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

کاربران جدید Apps Script اغلب درباره نحوه مدیریت مناطق زمانی توسط اشیای تاریخ سردرگم می‌شوند. یک روش طبیعی اما نادرست برای تصور کردن شیء تاریخ، زمان روی ساعت در یک منطقه زمانی است. برای مثال، در قطعه کد قبلی، برخی‌از کاربران به‌اشتباه فرض می‌کنند که date فقط در یک منطقه زمانی معتبر است، یعنی منطقه زمانی با ۵- ساعت اختلاف که برای ایجاد آن استفاده شده است. در این دیدگاه اشتباه، 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);

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

برای ارائه تاریخ به‌صورت رشته با قالب و منطقه زمانی خاص، از 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 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() نیز می‌شود.

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

به‌همین ترتیب، روش 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());

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