Google Ads komut dosyalarının genellikle tarih ve saatlerle çalışması gerekir. Sık kullanılan kullanım alanları arasında belirli bir tarih aralığı için rapor alma, kampanyaları veya reklam gruplarını belirli zamanlarda yayınlanacak şekilde planlama ve komut dosyasının son çalıştırıldığı zamanı bir e-tabloya aktarma yer alır. Bu kılavuzda, Google Ads komut dosyalarında tarih ve saatlerle çalışırken önemli kavramlar, yaygın 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, zaman içindeki 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 dosyası kullanıcıları, tarih nesnelerinin saat dilimlerini nasıl işlediği konusunda genellikle kafa karışıklığı yaşar. Bir tarih nesnesini doğal ancak yanlış bir şekilde düşünmenin yolu tek bir saat dilimindeki saattir. Örneğin, yukarıdaki snippet'te bazı kullanıcılar yanlışlıkla date işlevinin yalnızca tek bir saat diliminde, yani bunu oluşturmak için kullanılan -5 saatlik farkı olan saat diliminde geçerli olduğunu varsayar. Bu yanlış görüşe göre, date'ün diğer saat dilimlerinde kullanılabilmesi için "dönüştürülmesi" gerekir.
Bir tarih nesnesi hakkında düşünmenin doğru yolu, herhangi bir saat diliminden bağımsız olarak zaman içindeki belirli bir anı ifade eder. Belirli bir an, farklı saat dilimlerindeki saatlerde farklı görünse de aynı andır. Örneğin, şu snippet'i inceleyin:
// 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);
Bir tarih nesnesi zaman içindeki belirli bir anı temsil ettiğinden, saat dilimlerine göre "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 belirtilmiştir. Komut dosyanızı çalıştıran Google Ads hesabıyla ilişkilendirilmiş 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 günlüğe kaydedilen tarih nesneleri, 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);
Varsayılan saat dilimi, Google Ads hesabıyla ilişkili saat dilimine bakılmaksızın America/Los_Angeles (Pasifik) şeklindedir. Güncelleme veya başka amaçlar için tarih nesnesini özel bir biçim ve saat dilimi kullanarak dize olarak oluşturmak istiyorsanız her zaman Utilities.formatDate(date, timeZone,
format) kullanın.
Tarih nesnesi oluştururken varsayılan saat dilimi
Saat dilimi farkı sağlamayan bir dize kullanılarak tarih nesnesi oluşturulurken, Google Ads hesabıyla ilişkili saat diliminden bağımsız olarak saat diliminin America/Los_Angeles (Pasifik) 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 zamanı temsil etmesini sağlamak için her zaman saat dilimi farkı ekleyin.
Tarih nesnesi yöntemlerinde varsayılan saat dilimi
JavaScript tarih nesneleri, varsayılan saat dilimi varsayılan olarak kabul eden çeşitli yöntemlere sahiptir. Örneğin:
getFullYear()getMonth()getDate()getDay()getHours()getMinutes()
Bu yöntemler için set___() eşdeğerlerini (örneğin, setMonth()) ve getTimezoneOffset() de buna dahildir.
Google Ads komut dosyalarında, Google Ads hesabıyla ilişkili saat dilimine bakılmaksızın varsayılan saat dilimi America/Los_Angeles (Pasifik) olur. Bu nedenle, Google Ads hesabınız bu saat diliminde değilse genellikle bu yöntemleri kullanmaktan kaçınmanız gerekir.
Hesabınızın saat dilimindeki bir tarih nesnesi için yıl, ay, tarih, gün, saat veya dakika bilgilerini almak istiyorsanız Utilities.formatDate(date, timeZone,
format) öğesini, istediğiniz tarih veya saat dilimini belirten bir biçimle, AdsApp.currentAccount().getTimeZone() ise hesabınızın saat dilimini öğrenmek için kullanın.
Biçimlendirilmiş bir 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 her zaman MMMM dd, yyyy
HH:mm:ss Z biçiminde gönderin.
Örneğin, mevcut hesabın saat diliminde bugünün öğle saati için bir tarih nesnesi oluşturmak istiyorsanı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);
Bir tarih oluşturucuya iletilecek tarih dizeleri oluşturmak için "z" kalıbını kullanmayın. Oluşturucu her zaman bu kalıbı ayrıştıramaz. Yalnızca "Z" kalıbını kullanın.
Tarih hesaplamaları
Bazı komut dosyalarının, belirli bir tarihten X gün önce veya sonra bir tarih bulmak gibi basit matematik işlemleri yapması gerekir. Tarih hesaplaması yaparken getTime() değerini kullanın.
Bir tarih nesnesi üzerinde getTime() çağrısı yapıldığında, 1 Ocak 1970 UTC'den bu yana geçen milisaniye sayısı döndürülür. Bu değer üzerinde matematiksel işlemler 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 önceyi ifade eder.
Raporlama
AdsApp.search() kullanılarak bir rapor alınırken GAQL sorgusu, tarihlerin yyyy-MM-dd biçiminde belirtilmesini gerektirir (örneğin, 2021-06-30 30 Haziran 2021 olur).
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) değerini kullanın.
Örneğin, bir ila üç gün öncesine ait bir raporu 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 de dahil olmak üzere bir e-tabloya çıktı yazar. Bir e-tabloda tarih nesnesi ile hücre ayarlanırken, 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 bir e-tabloya istediğiniz şekilde yazıldığından emin olmak için e-tablonun saat dilimini Google Ads hesabınızın saat dilimine uyacak şekilde ayarlayın:
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());