このページは Cloud Translation API によって翻訳されました。

日時の設定

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, 2021 13:00:00 -0500');

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

AdWords スクリプトを使い始めたばかりのユーザーは、日付オブジェクトでのタイムゾーンの扱いについて混乱する場合がよくあります。自然ですが間違った言い方をすると、日付オブジェクトを タイムゾーンの時計を同じものにします。たとえば、上記のスニペットでは、date が 1 つのタイムゾーン（作成に使用した -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 広告アカウントに関連付けられているタイムゾーンを取得するには、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 広告アカウントに関連付けられているタイムゾーンにかかわらず「アメリカ、ロサンゼルス（太平洋標準時）」です。画像データをログにカスタム形式とタイムゾーンを使用した文字列としての日付オブジェクトをその他の目的には、常に Utilities.formatDate(date, timeZone, format) を使用します。

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

タイムゾーンを指定しない文字列を使用して日付オブジェクトを作成する場合タイムゾーンはアメリカ/ロサンゼルス（太平洋時間）と想定されます。 ただし、Google 広告アカウントに関連付けられているタイムゾーンは問いません。次に例を示します。

// 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 広告スクリプトでは、Google 広告アカウントに関連付けられているタイムゾーンに関係なく、デフォルトのタイムゾーンは America/Los_Angeles（太平洋時間）です。そのため、お客様の Google 広告アカウントがこのタイムゾーンでない限り、これらのメソッドは使用しないでください。

アカウントのタイムゾーンにある日付オブジェクトの年、月、日、時、分、秒を取得するには、必要な日付または時刻の部分を指定する形式で 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」パターンのみを使用します。

日付の計算

特定の日付から何日か前、または何日か後の日付を取得するなど、簡単な日付の計算が必要な場合があります。日付演算を行う場合は、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 広告スクリプトオブジェクトで使用できる 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, 2021 13:00:00 -0500 (Eastern Time)
const now = new Date();
spreadsheet.getRange('A1').setValue(now);

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

日付オブジェクトがスプレッドシートに正しく書き込まれるようにするには、スプレッドシートのタイムゾーンを、ご自身の Google 広告アカウントと同じタイムゾーンに設定します。

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

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