Ürünlerimiz hakkında görüşmek ve geri bildirimde bulunmak için Google Advertising and Measurement Community sunucusundaki resmi Google Ads Discord kanalına katılın.

Bu sayfa, Cloud Translation API ile çevrilmiştir.

Tarihler ve Saatlerle Çalışma

Google Ads komut dosyalarının genellikle tarih ve saatlerle çalışması gerekir. 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ı bir e-tabloya aktarma gibi yaygın kullanım alanları vardır. Bu kılavuzda, Google Ads komut dosyalarında tarih ve saatlerle çalışırken dikkat edilmesi gereken ö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, belirli bir zaman anını temsil eder. Yeni bir tarih nesnesi oluşturmanın çeşitli yolları 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, 2025 13:00:00 -0500');

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

Yeni Google Apps Komut Dosyaları kullanıcıları, tarih nesnelerinin saat dilimlerini nasıl işlediği konusunda genellikle kafa karışıklığı yaşar. Bir tarih nesnesini düşünmenin doğal ancak yanlış yolu, tek bir zaman dilimindeki bir saatin zamanı olarak düşünmektir. Örneğin, yukarıdaki snippet'te bazı kullanıcılar date öğesinin yalnızca bir saat diliminde (oluşturulurken kullanılan -5 saatlik saat dilimi) geçerli olduğunu yanlışlıkla varsayıyor. Bu hatalı görünümde, date değerinin diğer saat dilimlerinde kullanılabilmesi için "dönüştürülmesi" gerekir.

Bunun yerine, tarih nesnesini herhangi bir zaman diliminden bağımsız olarak belirli bir zaman anı olarak düşünmek doğru yaklaşımdır. Belirli bir an, farklı saat dilimlerindeki saatlerde farklı şekilde gösterilse 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, 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);

Tarih nesnesi belirli bir zamanı temsil ettiğinden saat dilimleri arasında "dönüştürülmesine" gerek yoktur. Bunun yerine, belirli bir saat dilimine göre biçimlendirilmiş bir dize olarak oluşturulabilir.

Bir tarihi belirli bir biçim ve saat dilimiyle dize olarak oluşturmak için Utilities.formatDate(date, timeZone, format) işlevini kullanın. Örneğin: 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\''));

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

Sık karşılaşılan sorunlar

Tarihlerle ilgili yaygın hatalardan bazıları aşağıda verilmiştir.

Tarih nesnesi günlüğe kaydedilirken varsayılan zaman dilimi

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

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

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

Varsayılan saat dilimi, Google Ads hesabıyla ilişkili saat diliminden bağımsız olarak Amerika/Los_Angeles (Pasifik saati) olur. Tarih nesnesini, günlük kaydı veya diğer amaçlar için ö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 uzaklığı sağlamayan bir dize kullanarak tarih nesnesi oluştururken, Google Ads hesabıyla ilişkili 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, 2025 13:00:00');

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

Dize kullanarak bir tarih nesnesi oluştururken, tarih nesnesinin istediğiniz zamanı temsil etmesini sağlamak için her zaman bir saat dilimi farkı ekleyin.

Tarih nesnesi yöntemlerinde varsayılan saat dilimi

JavaScript tarih nesnelerinin, varsayılan bir saat dilimini varsayan çeşitli yöntemleri vardır. Örneğin:

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

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

Google Ads komut dosyalarında varsayılan saat dilimi, Google Ads hesabıyla ilişkili saat diliminden bağımsız olarak Amerika/Los_Angeles (Pasifik saati) olur. 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 nesnesinin yılını, ayını, tarihini, gününü, saatini veya dakikasını almak için Utilities.formatDate(date, timeZone, format) işlevini istediğiniz tarih veya saat bölümünü belirten bir biçimle birlikte kullanın ve hesabınızın saat dilimini almak için AdsApp.currentAccount().getTimeZone() işlevini kullanın.

Biçimlendirilmiş bir tarih dizesinden tarih nesnesi oluşturma

Biçimlendirilmiş bir tarih dizesini tarih oluşturucusuna ileterek tarih nesnesi oluşturabilirsiniz. Örneğin:

const date = new Date('February 17, 2025 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 sağlayın.

Örneğin, mevcut hesabın saat diliminde bugün öğlen 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);

Oluşturucu her zaman ayrıştıramayacağından, tarih oluşturucuya iletilecek tarih dizeleri oluşturmak için "z" kalıbını kullanmayın. Yalnızca "Z" desenini kullanın.

Tarih işlemleri

Bazı komut dosyalarının tarihlerle basit matematik işlemleri yapması gerekir. Örneğin, belirli bir tarihten X gün önce veya sonraki tarihi bulma gibi. Tarih işlemleri yaparken getTime() kullanın. Bir tarih nesnesinde getTime() işlevini çağırmak, 1 Ocak 1970 UTC tarihinin başlangıcından bu yana geçen milisaniye sayısını döndürür. Bu değer üzerinde matematiksel işlemler yapabilir, ardından setTime() kullanarak yeni değeri bir tarih nesnesine uygulayabilir veya yeni bir tarih nesnesi oluştururken bunu parametre olarak sağlayabilirsiniz.

Ö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 önceydi.

Raporlama

AdsApp.search() kullanarak bir rapor alırken GAQL sorgusunda tarihler yyyy-MM-dd biçiminde belirtilmelidir (örneğin, 2025-06-30 30 Haziran 2025 olur).

Aynı şekilde, birçok Google Ads komut dosyası nesnesinde bulunan getStatsFor() yöntemi, tarihlerinin aynı biçimde belirtilmesini gerektirir. 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 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-tablodaki hücreyi tarih nesnesi geçirerek ayarlarken bu tarihi yorumlamak için e-tablonun saat dilimi kullanılır. Örneğin, saat dilimi Pasifik Saati olarak ayarlanmış bir e-tablomuz olduğunu varsayalım:

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

A1 hücresindeki değer 17-Şub-25 10:00:00 olur.

Tarih nesnelerinin e-tabloya beklendiği 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());

Ayrıca e-tablonun saatini manuel olarak da ayarlayabilirsiniz.