Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

日時の設定

Google 広告スクリプトでは日時の設定が必要になることがあります。一般的なユースケースとしては、特定の日付範囲のレポートを取得する、特定の時間にキャンペーンや広告グループをスケジュール設定して実行する、スクリプトが最後に実行された時刻をスプレッドシートに出力するなどが挙げられます。このガイドでは、Google 広告スクリプトで日時を扱う際の重要なコンセプト、よくある注意点、推奨されるアプローチについて説明します。

基本概念

Google 広告スクリプトで日時を扱うには、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, 2025 13:00:00 -0500');

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

スクリプトを初めて使用する方は、日付オブジェクトがタイムゾーンをどのように処理するのか混乱することがよくあります。日付オブジェクトを、1 つのタイムゾーンの時計の時刻として考えるのは自然ですが、正しくありません 。たとえば、前のスニペットでは、date は 1 つのタイムゾーン（作成に使用された -5 時間のオフセットのタイムゾーン）でのみ有効であると誤解するユーザーがいます。その誤った考え方では、他のタイムゾーンで使用するには date を「変換」する必要があります。

日付オブジェクトは、タイムゾーンに依存しない特定の時点として考えるのが正しい 方法です。特定の時点は、タイムゾーンによって時計の表示が異なりますが、同じ時点です。たとえば、次のスニペットを考えてみましょう。

// Create two date objects with different times and time zone 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);

日付オブジェクトは特定の時点を表すため、タイムゾーン間で「変換」する必要はありません。代わりに、特定のタイムゾーン用にフォーマットされた文字列としてレンダリングできます。

特定の日付とタイムゾーンで日付を文字列としてレンダリングするには、 Utilities.formatDate(date, timeZone, format)を使用します。たとえば、次のとおりです。

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

これらの例では、タイムゾーン ID を使用してタイムゾーンを直接指定しています。スクリプトを実行している Google 広告アカウントに関連付けられているタイムゾーンを取得するには、を使用します AdsApp.currentAccount().getTimeZone()。

主な注意点

日付に関するよくある注意点を次に示します。

日付オブジェクトのログ記録時のデフォルトのタイムゾーン

Logger.log() を使用して日付オブジェクトを直接ログに記録すると、デフォルトの形式とタイムゾーンでレンダリングされます。たとえば、次のとおりです。

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

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

デフォルトのタイムゾーンは America/Los_Angeles（太平洋時間）です。これは、Google 広告アカウントに関連付けられているタイムゾーンに関係なく適用されます。ログ記録などの目的で、カスタム形式とタイムゾーンを使用して日付オブジェクトを文字列としてレンダリングする場合は、常に Utilities.formatDate(date, timeZone, format)を使用してください。

日付オブジェクトの作成時のデフォルトのタイムゾーン

タイムゾーンのオフセットを指定しない文字列を使用して日付オブジェクトを作成する場合、タイムゾーンは America/Los_Angeles（太平洋時間）とみなされます。これは、Google 広告アカウントに関連付けられているタイムゾーンに関係なく適用されます。たとえば、次のとおりです。

// Create a date without specifying the time zone offset.
const date = new Date('February 17, 2025 13:00:00');

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

文字列を使用して日付オブジェクトを作成する場合は、日付オブジェクトが実際に必要な時点を表すように、必ずタイムゾーンのオフセットを含めてください。

日付オブジェクトメソッドのデフォルトのタイムゾーン

JavaScript の日付オブジェクトには、デフォルトのタイムゾーンを想定するメソッドがいくつかあります。たとえば、次のものがあります。

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

これには、これらのメソッドの set___() に相当するもの（setMonth() など）と getTimezoneOffset() も含まれます。

Google 広告スクリプトでは、デフォルトのタイムゾーンは America/Los_Angeles（太平洋時間）です。これは、Google 広告アカウントに関連付けられているタイムゾーンに関係なく適用されます。そのため、Google 広告アカウントがこのタイムゾーンにない場合は、通常、これらのメソッドの使用は避ける必要があります。

アカウントのタイムゾーンで日付オブジェクトの年、月、日、曜日、時、分を取得するには、 Utilities.formatDate(date, timeZone, format) を使用して、日付または時刻の必要な部分を指定します。また、 AdsApp.currentAccount().getTimeZone() を使用して、アカウントのタイムゾーンを取得します。

形式を指定した日付の文字列を使って日付オブジェクトを作成する

日付オブジェクトを作成する際、形式を指定した日付の文字列を日付コンストラクタに含めることができます。たとえば、次のとおりです。

const date = new Date('February 17, 2025 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」パターンのみを使用してください。

日付の計算

特定の日付から何日か前、または何日か後の日付を取得するなど、簡単な日付の計算が必要なスクリプトがあります。日付の計算を行う場合は、getTime() を使用します。日付オブジェクトで getTime() を呼び出すと、1970 年 1 月 1 日午前 0 時（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 形式で指定する必要があります（たとえば、2025-06-30 は 2025 年 6 月 30 日になります）。

同様に、多くの Google 広告スクリプトオブジェクトで使用できる 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 広告スクリプトでは、日付オブジェクトを含む出力がスプレッドシートに書き込まれることがよくあります。日付オブジェクトを渡してスプレッドシートのセルを設定すると、スプレッドシートのタイムゾーンを使用して日付が解釈されます。たとえば、タイムゾーンが太平洋時間に設定されているスプレッドシートがあるとします。

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

A1 の値は 17-Feb-25 10:00:00 になります。

日付オブジェクトが想定どおりにスプレッドシートに書き込まれるようにするには、スプレッドシートのタイムゾーンを Google 広告アカウントのタイムゾーンと一致するように設定します。

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

スプレッドシートの時刻を手動で設定することもできます。