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, 2021 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 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);
날짜 객체는 특정 시점을 나타내므로 시간대를 '변환'할 필요가 없습니다. 대신 특정 시간대에 맞게 형식이 지정된 문자열로 렌더링할 수 있습니다.
특정 형식과 시간대를 사용하여 날짜를 문자열로 렌더링하려면 Utilities.formatDate(date, timeZone,
format)를 사용하세요.
예를 들면 다음과 같습니다.
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\''));
이 예에서는 시간대 ID를 사용하여 직접 시간대를 지정했습니다. 스크립트를 실행하는 Google Ads 계정과 연결된 시간대를 가져오려면 AdsApp.currentAccount().getTimeZone()를 사용하세요.
일반적인 문제
날짜 객체를 로깅할 때의 기본 시간대
Logger.log()를 사용하여 날짜 객체를 직접 로깅하면 기본 형식과 시간대를 사용하여 렌더링됩니다. 예를 들면 다음과 같습니다.
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 계정과 연결된 시간대와 관계없이 America/Los_Angeles(태평양 표준시)입니다. 로깅이나 기타 목적으로 맞춤 형식과 시간대를 사용하여 날짜 객체를 문자열로 렌더링하려면 항상 Utilities.formatDate(date, timeZone,
format)을 사용하세요.
날짜 객체를 만들 때의 기본 시간대
시간대 오프셋을 제공하지 않는 문자열을 사용하여 날짜 객체를 만들면 Google Ads 계정과 연결된 시간대와 관계없이 시간대가 America/Los_Angeles(태평양 시간)으로 간주됩니다. 예를 들면 다음과 같습니다.
// 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);
문자열을 사용하여 날짜 객체를 만들 때는 날짜 객체가 실제로 원하는 순간을 나타내도록 항상 시간대 오프셋을 포함합니다.
날짜 객체 메서드의 기본 시간대
JavaScript 날짜 객체에는 기본 시간대를 가정하는 다음과 같은 여러 메서드가 있습니다.
getFullYear()getMonth()getDate()getDay()getHours()getMinutes()
여기에는 이러한 메서드의 set___() 등가 항목(예: setMonth()) 및 getTimezoneOffset()도 포함됩니다.
Google Ads 스크립트에서 기본 시간대는 Google Ads 계정과 연결된 시간대와 관계없이 America/Los_Angeles(태평양 표준시)입니다. 따라서 Google Ads 계정이 이 시간대에 있지 않는 한 일반적으로 이러한 메서드를 사용하지 않는 것이 좋습니다.
계정의 시간대에서 날짜 객체의 연도, 월, 일, 시간 또는 분을 가져오려면 원하는 날짜 또는 시간의 일부를 지정하는 형식과 함께 Utilities.formatDate(date, timeZone,
format)를 사용하고 AdsApp.currentAccount().getTimeZone()를 사용하여 계정의 시간대를 가져옵니다.
형식이 지정된 날짜 문자열에서 날짜 객체 만들기
형식이 지정된 날짜 문자열을 날짜 생성자에 전달하여 날짜 객체를 만들 수 있습니다. 예를 들면 다음과 같습니다.
const date = new Date('February 17, 2021 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()를 호출하면 1970년 1월 1일(UTC) 시작 이후의 밀리초 수가 반환됩니다. 이 값에 수학을 실행한 다음 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 형식으로 지정해야 합니다(예: 2021-06-30은 2021년 6월 30일).
마찬가지로 여러 Google Ads 스크립트 객체에서 사용할 수 있는 getStatsFor()
메서드에서는 날짜를 동일한 형식으로 지정해야 합니다. Utilities.formatDate(date, timeZone,
format)를 사용하여 날짜 객체의 형식을 이 형식으로 지정합니다.
예를 들어 1~3일 전의 보고서를 검색하려면 다음 단계를 따르세요.
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, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);
A1의 값은 2021년 2월 17일 10시 00분 00초입니다.
날짜 객체가 예상대로 스프레드시트에 쓰여지도록 하려면 스프레드시트의 시간대를 Google Ads 계정의 시간대와 일치하도록 설정하세요.
spreadsheet.setSpreadsheetTimeZone(AdsApp.currentAccount().getTimeZone());
스프레드시트의 시간을 수동으로 설정할 수도 있습니다.