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

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) का इस्तेमाल करें.

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

टाइम ज़ोन का ऑफ़सेट न देने वाली स्ट्रिंग का इस्तेमाल करके तारीख का ऑब्जेक्ट बनाते समय, टाइम ज़ोन को 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);

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

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

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

  • 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() को कॉल करने पर, 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-फ़रवरी-2025 10:00:00 होगी.

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

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

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