तारीख और समय के साथ काम करना

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

किसी डेट ऑब्जेक्ट के समय के किसी खास पल को दिखाने की वजह से, इसे अलग-अलग टाइम ज़ोन के लिए "कन्वर्ट" करने की ज़रूरत नहीं होती. इसके बजाय, इसे किसी खास टाइम ज़ोन के लिए फ़ॉर्मैट की गई स्ट्रिंग के तौर पर दिखाया जा सकता है.

किसी तारीख को किसी खास फ़ॉर्मैट और टाइम ज़ोन के साथ स्ट्रिंग के तौर पर दिखाने के लिए, 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);

डिफ़ॉल्ट टाइम ज़ोन, अमेरिका/लॉस_एंजेलिस (पैसिफ़िक टाइम) होता है. यह Google Ads खाते से जुड़े टाइम ज़ोन पर निर्भर नहीं करता. अगर आपको लॉगिंग या अन्य उद्देश्यों के लिए, डेट ऑब्जेक्ट को कस्टम फ़ॉर्मैट और टाइम ज़ोन का इस्तेमाल करके स्ट्रिंग के तौर पर दिखाना है, तो हमेशा Utilities.formatDate(date, timeZone, format)का इस्तेमाल करें.

डेट ऑब्जेक्ट बनाते समय डिफ़ॉल्ट टाइम ज़ोन

किसी ऐसी स्ट्रिंग का इस्तेमाल करके डेट ऑब्जेक्ट बनाने पर जिसमें टाइम ज़ोन ऑफ़सेट की जानकारी नहीं दी गई है, टाइम ज़ोन को अमेरिका/लॉस_एंजेलिस (पैसिफ़िक टाइम) माना जाता है. यह 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);

स्ट्रिंग का इस्तेमाल करके डेट ऑब्जेक्ट बनाते समय, हमेशा टाइम ज़ोन ऑफ़सेट शामिल करें. इससे यह पक्का किया जा सकेगा कि डेट ऑब्जेक्ट, समय के उस पल को दिखाए जिसे आपको दिखाना है.

डेट ऑब्जेक्ट के तरीकों में डिफ़ॉल्ट टाइम ज़ोन

JavaScript के डेट ऑब्जेक्ट में कई ऐसे तरीके होते हैं जो डिफ़ॉल्ट टाइम ज़ोन मानते हैं. जैसे:

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

इनमें इन तरीकों के set___() के बराबर के तरीके (उदाहरण के लिए, setMonth()) और getTimezoneOffset() भी शामिल हैं.

Google Ads की स्क्रिप्ट में, डिफ़ॉल्ट टाइम ज़ोन अमेरिका/लॉस_एंजेलिस (पैसिफ़िक टाइम) होता है. यह 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() को कॉल करने पर, 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.

इसी तरह, Google Ads स्क्रिप्ट के कई ऑब्जेक्ट पर उपलब्ध 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'));

स्प्रेडशीट

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-फ़रवरी-25 10:00:00 होगी.

यह पक्का करने के लिए कि डेट ऑब्जेक्ट, स्प्रेडशीट में आपकी उम्मीद के मुताबिक लिखे जाएं, स्प्रेडशीट का टाइम ज़ोन अपने Google Ads खाते के टाइम ज़ोन से मैच करें:

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

स्प्रेडशीट का टाइम मैन्युअल तरीके से भी सेट किया जा सकता है.