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

اسکریپت های تبلیغات گوگل اغلب باید با تاریخ و زمان کار کنند. موارد استفاده متداول شامل بازیابی گزارش‌ها برای یک محدوده تاریخی خاص، زمان‌بندی کمپین‌ها یا گروه‌های تبلیغاتی برای اجرا در زمان‌های خاص، و خروجی به صفحه‌گسترده زمان آخرین اجرای اسکریپت است. این راهنما مفاهیم مهم، مشکلات رایج و رویکردهای توصیه شده را هنگام کار با تاریخ و زمان در اسکریپت‌های 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, 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);

توجه: در داخل، جاوا اسکریپت یک شی تاریخ را به عنوان تعداد میلی ثانیه از 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);

منطقه زمانی پیش‌فرض آمریکا/Los_Angeles (به وقت اقیانوس آرام)، بدون توجه به منطقه زمانی مرتبط با حساب Google Ads است. اگر می‌خواهید شی تاریخ را به‌صورت رشته‌ای با استفاده از قالب و منطقه زمانی سفارشی برای ورود به سیستم یا اهداف دیگر رندر کنید، همیشه از Utilities.formatDate(date, timeZone, format) استفاده کنید.

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

هنگام ایجاد یک شی تاریخ با استفاده از رشته‌ای که فاصله منطقه زمانی ارائه نمی‌کند ، منطقه زمانی آمریکا/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);

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

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

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

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

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

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

برای دریافت سال، ماه، تاریخ، روز، ساعت یا دقیقه برای یک شی تاریخ در منطقه زمانی حساب خود، از Utilities.formatDate(date, timeZone, format) با قالبی استفاده کنید که بخشی از تاریخ یا زمان مورد نظر را مشخص می‌کند، و از AdsApp.currentAccount().getTimeZone() برای دریافت منطقه زمانی حساب خود استفاده کنید.

ایجاد یک شی تاریخ از یک رشته تاریخ قالب بندی شده

شما می توانید با ارسال یک رشته تاریخ فرمت شده به سازنده تاریخ، یک شی تاریخ ایجاد کنید. مثلا:

const date = new Date('February 17, 2021 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() بر روی یک شیء date، تعداد میلی‌ثانیه‌ها را از آغاز 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());

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