Tarihler ve Saatlerle Çalışma

Google Ads komut dosyalarının genellikle tarih ve saatlerle çalışması gerekir. Yaygın kullanım alanları arasında belirli bir tarih aralığı için rapor alma, kampanyaları veya reklam gruplarını belirli zamanlarda çalışacak şekilde planlama ve komut dosyasının en son çalıştırıldığı zamanı e-tabloya çıkarma yer alır. Bu kılavuzda, Google Ads komut dosyalarında tarih ve saatlerle çalışırken önemli kavramlar, yaygın karşılaşılan hatalar ve önerilen yaklaşımlar açıklanmaktadır.

Temel kavramlar

Google Ads komut dosyalarında tarih ve saatlerle çalışmak için JavaScript'in yerleşik tarih nesnesini kullanın. JavaScript tarih nesnesi, zamandaki belirli bir anı temsil eder. Yeni bir tarih nesnesi oluşturmanın birkaç yolu vardır:

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

Yeni Komut Dosyaları kullanıcıları genellikle, tarih nesnelerinin saat dilimlerini işleme biçimi nedeniyle kafa karışıklığı yaşar. Bir tarih nesnesini düşünmenin doğal ancak yanlış bir yolu, tek bir saat diliminde bulunan saat gibidir. Örneğin, yukarıdaki snippet'te bazı kullanıcılar, date özelliğinin yalnızca tek bir saat diliminde, yani -5 saatlik farkı içeren saat diliminde geçerli olduğunu yanlış şekilde varsaymaktadır. Bu hatalı görünümde date öğesinin diğer saat dilimlerinde kullanılabilmesi için "dönüştürülmesi" gerekir.

Bunun yerine, bir tarih nesnesini düşünmenin doğru yolu, herhangi bir saat diliminden bağımsız olarak zamanda bulunan belirli bir an gibidir. Belirli bir an, farklı saat dilimlerindeki saatlerde farklı gösterilse de aynı andır. Örneğin, şu snippet'i ele alalım:

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

Not: JavaScript, dahili olarak bir tarih nesnesini 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısı olarak temsil eder.

Tarih nesnesi, zamandaki belirli bir anı temsil ettiğinden, saat dilimleri arasında "dönüştürülmesine" gerek yoktur. Bunun yerine, belirli bir saat dilimi için biçimlendirilmiş bir dize olarak oluşturulabilir.

Bir tarihi, belirli bir biçime ve saat dilimine sahip bir dize olarak oluşturmak için Utilities.formatDate(date, timeZone, format) değerini kullanın. Örneğin:

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\''));

Bu örneklerde saat dilimi, doğrudan bir saat dilimi kimliği kullanılarak belirtilmektedir. Komut dosyanızı çalıştıran Google Ads hesabıyla ilişkili saat dilimini almak için AdsApp.currentAccount().getTimeZone() değerini kullanın.

Sık karşılaşılan tehlikeler

Bir tarih nesnesini günlüğe kaydederken varsayılan saat dilimi

Logger.log() kullanılarak doğrudan bir tarih nesnesi günlüğe kaydedildiğinde varsayılan biçim ve saat dilimi kullanılarak oluşturulur. Örneğin:

const date = new Date('February 17, 2021 13:00:00 -0500');

// Wed Feb 17 10:00:00 GMT-08:00 2021
console.log(date);

Google Ads hesabıyla ilişkilendirilen saat diliminden bağımsız olarak varsayılan saat dilimi Amerika/Los_Angeles (Pasifik saati) şeklindedir. Tarih nesnesini günlük kaydı veya diğer amaçlarla özel bir biçim ve saat dilimi kullanarak dize olarak oluşturmak isterseniz her zaman Utilities.formatDate(date, timeZone, format) kullanın.

Tarih nesnesi oluştururken varsayılan saat dilimi

Saat dilimi farkı sağlamayan bir dize kullanarak tarih nesnesi oluştururken, Google Ads hesabıyla ilişkilendirilen saat diliminden bağımsız olarak saat diliminin Amerika/Los_Angeles (Pasifik saati) olduğu varsayılır. Örneğin:

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

Bir dize kullanarak tarih nesnesi oluştururken, tarih nesnesinin gerçekten istediğiniz anı temsil ettiğinden emin olmak için her zaman bir saat dilimi farkı ekleyin.

Tarih nesnesi yöntemlerinde varsayılan saat dilimi

JavaScript tarih nesneleri, varsayılan saat dilimini varsayan çeşitli yöntemlere sahiptir. Örneğin:

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

Buna, bu yöntemlerin set___() eşdeğerleri (örneğin, setMonth()) ve getTimezoneOffset() de dahildir.

Google Ads komut dosyalarında, Google Ads hesabıyla ilişkilendirilen saat diliminden bağımsız olarak varsayılan saat dilimi America/Los_Angeles (Pasifik saati) şeklindedir. Bu nedenle, Google Ads hesabınız bu saat diliminde değilse, genellikle bu yöntemleri kullanmaktan kaçınmalısınız.

Hesabınızın saat dilimindeki bir tarih nesnesi için yıl, ay, tarih, gün, saat veya dakikayı almak üzere Utilities.formatDate(date, timeZone, format) biçiminin istediğiniz tarih veya saat bölümünü belirten bir biçimde Utilities.formatDate(date, timeZone, format) kullanın. Hesabınızın saat dilimini almak için ise AdsApp.currentAccount().getTimeZone() kullanın.

Biçimlendirilmiş tarih dizesinden tarih nesnesi oluşturma

Tarih oluşturucuya biçimlendirilmiş bir tarih dizesi ileterek tarih nesnesi oluşturabilirsiniz. Örneğin:

const date = new Date('February 17, 2021 13:00:00 -0500');

Oluşturucu yalnızca belirli tarih dizesi biçimlerini ayrıştırabilir. Tarih dizenizin doğru şekilde ayrıştırıldığından emin olmak için bunu her zaman MMMM dd, yyyy HH:mm:ss Z biçiminde sağlayın.

Örneğin, geçerli hesabın saat diliminde bugün öğle saati için bir tarih nesnesi oluşturmak için:

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

Bir tarih oluşturucuya geçirilecek tarih dizeleri oluşturmak için "z" modelini kullanmayın. Aksi takdirde kurucu her zaman bunu ayrıştıramaz. Yalnızca "Z" kalıbını kullanın.

Tarih hesaplaması

Bazı komut dosyalarının, belirli bir tarihten X gün önceki veya sonraki bir tarihi bulmak gibi tarihlerle basit matematik işlemleri yapması gerekir. Tarih hesaplaması yaparken getTime() kullanın. Bir tarih nesnesinde getTime() çağrısı, 1 Ocak 1970 (UTC) başlangıcından itibaren geçen milisaniye sayısını döndürür. Bu değer üzerinde matematik işlemleri yapabilir, ardından yeni değeri setTime() kullanarak veya yeni bir tarih nesnesi oluştururken parametre olarak sağlayarak bir tarih nesnesine uygulayabilirsiniz.

Örneğin:

const MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
const now = new Date();
const yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

Bu örnekte, yesterday tam olarak 24 saat öncedir.

Raporlama

AdsApp.search() kullanılarak rapor alınırken GAQL sorgusu tarihlerin yyyy-MM-dd biçiminde belirtilmesini gerektirir (ör. 2021-06-30 değeri 30 Haziran 2021'dir).

Benzer şekilde, birçok Google Ads komut dosyası nesnesinde kullanılabilen getStatsFor() yöntemi, tarihlerin aynı biçimde belirtilmesini gerektirir. Bir tarih nesnesini bu biçimde biçimlendirmek için Utilities.formatDate(date, timeZone, format) kullanın.

Örneğin, bir ila üç gün öncesine ait bir rapor almak için:

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

E-tablolar

Google Ads komut dosyaları genellikle tarih nesneleri dahil olmak üzere bir e-tabloya çıktı yazar. Bir e-tabloda bir tarih nesnesini ileterek hücre ayarlarken, bu tarihi yorumlamak için e-tablonun saat dilimi kullanılır. Örneğin, saat dilimi Pasifik Saati'ne ayarlanmış bir e-tablomuz olduğunu varsayalım:

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

A1'deki değer 17-Şub-21 10:00:00 olur.

Tarih nesnelerinin e-tabloya beklediğiniz gibi yazıldığından emin olmak için e-tablonun saat dilimini Google Ads hesabınızın saat dilimiyle eşleşecek şekilde ayarlayın:

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

Bir e-tablonun zamanını manuel olarak da ayarlayabilirsiniz.