날짜 및 시간 다루기

Google Ads 스크립트에는 날짜와 시간을 지정해야 하는 경우가 많습니다. 일반적인 사용 사례로는 특정 기간의 보고서 검색, 특정 시간에 캠페인 또는 광고 그룹 실행 예약, 스크립트가 마지막으로 실행된 시간 스프레드시트 출력 등이 있습니다. 이 가이드에서는 Google Ads 스크립트에서 날짜와 시간을 작업할 때 중요한 개념, 일반적인 문제점, 권장 방법을 설명합니다.

기본 개념

Google Ads 스크립트에서 날짜와 시간을 사용하려면 자바스크립트에 내장된 날짜 객체를 사용하세요. 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);

참고: 내부적으로 JavaScript는 날짜 객체를 1970년 1월 1일 UTC 이후의 밀리초 수로 나타냅니다.

날짜 객체는 시간의 특정 시점을 나타내므로 여러 시간대 간에 '변환'할 필요가 없습니다. 특정 시간대에 맞게 형식이 지정된 문자열로 렌더링될 수 있습니다.

날짜를 특정 형식 및 시간대가 포함된 문자열로 렌더링하려면 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 계정과 연결된 시간대와 관계없이 미국/로스앤젤레스 (태평양 표준시)입니다. 로깅 또는 기타 목적으로 커스텀 형식 및 시간대를 사용하여 날짜 객체를 문자열로 렌더링하려면 항상 Utilities.formatDate(date, timeZone, format)를 사용하세요.

날짜 객체 생성 시 기본 시간대

시간대 오프셋을 제공하지 않는 문자열을 사용하여 날짜 객체를 만들면 Google Ads 계정과 연결된 시간대와 관계없이 미국/로스앤젤레스 (태평양 표준시)로 간주됩니다. 예를 들면 다음과 같습니다.

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

문자열을 사용하여 날짜 객체를 만들 때는 항상 시간대 오프셋을 포함하여 날짜 객체가 실제로 원하는 시간을 나타내도록 해야 합니다.

날짜 객체 메서드의 기본 시간대

자바스크립트 날짜 객체에는 다음과 같이 기본 시간대를 가정하는 여러 메서드가 있습니다.

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

스프레드시트의 시간을 수동으로 설정할 수도 있습니다.