التعامل مع التواريخ والأوقات

غالبًا ما تحتاج نصوص "إعلانات Google" البرمجية إلى العمل مع التواريخ والأوقات. تشمل حالات الاستخدام الشائعة استرداد التقارير لنطاق زمني محدّد، وجدولة الحملات أو المجموعات الإعلانية لعرضها في أوقات محدّدة، وإخراج الوقت الذي تم فيه تنفيذ النص البرمجي آخر مرة إلى جدول بيانات. يوضّح هذا الدليل المفاهيم المهمة والأخطاء الشائعة والأساليب المقترَحة عند التعامل مع التواريخ والأوقات في نصوص "إعلانات Google" البرمجية.

المفاهيم الأساسية

للتعامل مع التواريخ والأوقات في نصوص "إعلانات Google" البرمجية، استخدِم عنصر التاريخ المضمّن في 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, 2025 13:00:00 -0500');

// Create a copy of an existing date object.
let copy = new Date(date);

غالبًا ما يشعر مستخدمو "برمجة Google النصية" الجدد بالارتباك بشأن طريقة تعامل عناصر التاريخ مع المناطق الزمنية. الطريقة غير الصحيحة الشائعة للتفكير في عنصر التاريخ هي الوقت على ساعة في منطقة زمنية واحدة. على سبيل المثال، في المقتطف أعلاه، يفترض بعض المستخدمين بشكل خاطئ أنّ date صالح فقط في منطقة زمنية واحدة، وهي المنطقة الزمنية التي تم إنشاؤه فيها مع إزاحة مقدارها 5 ساعات. في هذا العرض الخاطئ، يجب "تحويل" date لاستخدامه في مناطق زمنية أخرى.

بدلاً من ذلك، فإنّ الطريقة الصحيحة للتعامل مع عنصر التاريخ هي اعتباره لحظة معيّنة في الوقت بغض النظر عن أي منطقة زمنية. على الرغم من أنّ لحظة معيّنة تظهر بشكل مختلف على الساعات في مناطق زمنية مختلفة، إلا أنّها اللحظة نفسها. على سبيل المثال، إليك المقتطف التالي:

// Create two date objects with different times and timezone 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" الذي ينفّذ البرنامج النصي، استخدِم 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". إذا أردت عرض عنصر التاريخ كسلسلة باستخدام تنسيق مخصّص ومنطقة زمنية مخصّصة لأغراض التسجيل أو غيرها، استخدِم دائمًا Utilities.formatDate(date, timeZone, format).

المنطقة الزمنية التلقائية عند إنشاء عنصر تاريخ

عند إنشاء عنصر تاريخ باستخدام سلسلة لا توفّر إزاحة المنطقة الزمنية، يُفترض أنّ المنطقة الزمنية هي America/Los_Angeles (توقيت المحيط الهادئ)، بغض النظر عن المنطقة الزمنية المرتبطة بحساب "إعلانات Google". على سبيل المثال:

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

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

عند إنشاء عنصر تاريخ باستخدام سلسلة، احرص دائمًا على تضمين إزاحة المنطقة الزمنية لضمان أنّ عنصر التاريخ يمثّل اللحظة الزمنية التي تريدها فعلاً.

المنطقة الزمنية التلقائية في طرق كائن التاريخ

تتضمّن عناصر التاريخ في JavaScript عدة طرق تفترض منطقة زمنية تلقائية، مثل:

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

ويشمل ذلك أيضًا مكافئاتها set___() (على سبيل المثال، setMonth()) وgetTimezoneOffset().

في نصوص "إعلانات Google" البرمجية، تكون المنطقة الزمنية التلقائية هي America/Los_Angeles (توقيت المحيط الهادئ)، بغض النظر عن المنطقة الزمنية المرتبطة بحساب "إعلانات Google". لذلك، ما لم يكن حسابك على "إعلانات Google" في هذه المنطقة الزمنية، عليك عمومًا تجنُّب استخدام هذه الطرق.

للحصول على السنة أو الشهر أو التاريخ أو اليوم أو الساعات أو الدقائق لكائن تاريخ في المنطقة الزمنية لحسابك، استخدِم 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() على عنصر تاريخ إلى عرض عدد المللي ثانية منذ بداية 1 يناير 1970 بالتوقيت العالمي المنسق. يمكنك إجراء عمليات حسابية على هذه القيمة، ثم تطبيق القيمة الجديدة على عنصر التاريخ باستخدام 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 (على سبيل المثال، سيكون 2025-06-30 هو 30 يونيو 2025).

وبالمثل، تتطلّب الطريقة getStatsFor() المتوفّرة في العديد من عناصر نصوص "إعلانات Google" البرمجية تحديد التواريخ بالتنسيق نفسه. استخدِم 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" البرمجية الناتج في جدول بيانات، بما في ذلك عناصر التاريخ. عند ضبط خلية في جدول بيانات من خلال تمرير عنصر تاريخ، يتم استخدام المنطقة الزمنية لجدول البيانات لتفسير هذا التاريخ. على سبيل المثال، لنفترض أنّ لدينا جدول بيانات تم ضبط المنطقة الزمنية فيه على توقيت المحيط الهادئ:

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

ستكون القيمة في الخلية A1 هي 25-02-17 10:00:00.

لضمان كتابة عناصر التاريخ في جدول بيانات على النحو المتوقّع، اضبط المنطقة الزمنية لجدول البيانات لتتطابق مع المنطقة الزمنية لحسابك على "إعلانات Google" باتّباع الخطوات التالية:

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

يمكنك أيضًا ضبط وقت جدول البيانات يدويًا.