日時の設定

AdWords スクリプトでは日時の設定が必要になることがあります。たとえば、特定の期間のレポートを取得する、キャンペーンや広告グループが特定の日時に実施されるようスケジュールを設定する、スクリプトが最後に実行された時間をスプレッドシートに出力する場合などに日時設定を使用します。ここでは、AdWords スクリプトで日時を設定するうえで重要な概念、主な注意点、おすすめのアプローチについて説明します。

基本概念

AdWords スクリプトで日時を設定するには、JavaScript の組み込み関数である日付オブジェクトを使用します。JavaScript の日付オブジェクトを使用すると、特定の日時が表示されます。新しく日付オブジェクトを作成するには、次のような複数の方法があります。

// Create a date object for the current date and time.
var now = new Date();

// Create a date object for a past date and time using a formatted string.
var date = new Date('February 17, 2016 13:00:00 -0500');

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

AdWords スクリプトを使い始めたばかりのユーザーは、日付オブジェクトでのタイムゾーンの扱いについて混乱する場合がよくあります。日付オブジェクトが指すのはある特定のタイムゾーンの時刻であると考えるのは自然ですが、これは正しくありません。たとえば、上記のスニペットの場合、設定した date が有効なのは、1 つのタイムゾーン(日付オブジェクトで設定したのと同じ、協定世界時(UTC)との時差 -5 時間のタイムゾーン)のみであると誤解するユーザーがいます。この考え方では、他のタイムゾーンで同じ date を設定する場合は「変換」が必要だということになります。

しかし、日付オブジェクトが指しているのは、タイムゾーンとは独立した特定の瞬間であるというのが正しい考え方です。ある特定の瞬間は、タイムゾーンが変われば時計での表示は変わりますが、同じ瞬間であることは変わりません。たとえば、次のコードをご覧ください。

// Create two date objects with different times and timezone offsets.
var date1 = new Date('February 17, 2016 13:00:00 -0500');
var date2 = new Date('February 17, 2016 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.
Logger.log(date1.getTime() == date2.getTime());

// False, as the dates are separate objects, though they happen to
// represent the same moment in time.
Logger.log(date1 == date2);

日付オブジェクトが示しているのはある特定の瞬間であるため、タイムゾーンごとに「変換」する必要はありません。なお、日付を特定のタイムゾーンの形式に合った文字列に整形することは可能です。

特定のタイムゾーンと形式に合わせた文字列として日時を表示するには、Utilities.formatDate(date, timeZone, format) を使用します。たとえば、次のとおりです。

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

// February 17, 2016 13:00:00 -0500
Logger.log(Utilities.formatDate(date, 'America/New_York', 'MMMM dd, yyyy HH:mm:ss Z'));

// February 17, 2016 10:00:00 -0800
Logger.log(Utilities.formatDate(date, 'America/Los_Angeles', 'MMMM dd, yyyy HH:mm:ss Z'));

// 2016-02-17T18:00:00.000Z
Logger.log(Utilities.formatDate(date, 'Etc/GMT', 'yyyy-MM-dd\'T\'HH:mm:ss.SSS\'Z\''));

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

主な注意点

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

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

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

// Wed Feb 17 10:00:00 GMT-08:00 2016
Logger.log(date);

デフォルトのタイムゾーンは、AdWords アカウントに関連付けられているタイムゾーンにかかわらず「アメリカ、ロサンゼルス(太平洋標準時)」です。日付オブジェクトをご希望の形式やタイムゾーンで文字列として表示したい場合は、Utilities.formatDate(date, timeZone, format) を使用します。

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

タイムゾーン オフセットを含まない文字列で日付オブジェクトを作成すると、AdWords アカウントに関連付けられているタイムゾーンにかかわらず、「アメリカ、ロサンゼルス(太平洋標準時)」が適用されます。たとえば、次のとおりです。

// Create a date without specifying the timezone offset.
var date = new Date('February 17, 2016 13:00:00');

// Wed Feb 17 13:00:00 GMT-08:00 2016
Logger.log(date);

文字列を使って日付オブジェクトを作成する場合は、タイムゾーン オフセットを入力して、ご希望の時刻が表示されるようにします。

日付オブジェクトのメソッドが使用できるデフォルトのタイムゾーン

JavaScript の日付オブジェクトには、タイムゾーンがデフォルトの場合に使用できるメソッドがあります。getFullYear()getMonth()getDate()getDay()getHours()getMinutes()、およびこれらの先頭を set___() に置き換えた各メソッドと、getTimezoneOffet() です。AdWords スクリプトのデフォルトのタイムゾーンは、AdWords アカウントに関連付けられているタイムゾーンにかかわらず「アメリカ、ロサンゼルス(太平洋標準時)」です。ご自身の AdWords アカウントがこのタイムゾーンでなければ、上記のメソッドを使用しないようにしてください。

ご自身のアカウントのタイムゾーンの日付オブジェクトとして年、月、日、曜日、時間、分を取得するには、Utilities.formatDate(date, timeZone, format) を使用してご希望の日付や時間の形式を指定し、AdWordsApp.currentAccount().getTimeZone() を使用してアカウントのタイムゾーンを取得します。

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

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

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

コンストラクタが解析できるのは、特定の日付文字列の形式のみです。日付の文字列が正しく解析されるようにするには、必ず MMMM dd, yyyy HH:mm:ss Z の形式で入力します。

たとえば、アカウントに現在設定されているタイムゾーンで、今日の正午の日付オブジェクトを作成する場合、次のようになります。

var now = new Date();
var timeZone = AdWordsApp.currentAccount().getTimeZone();
var noonString = Utilities.formatDate(now, timeZone,
                                      'MMMM dd, yyyy 12:00:00 Z')
var noon = new Date(noonString);

日付コンストラクタに日付文字列を含める際は、コンストラクタが解析できない場合があるため、「z」のパターン文字を使用しないでください。「Z」のパターン文字のみを使用してください。

日付の計算

特定の日付から何日か前、または何日か後の日付を取得するなど、簡単な日付の計算が必要な場合があります。このような場合には、getTime() を使用します。日付オブジェクトで getTime() を実行すると、協定世界時(UTC)1970 年 1 月 1 日から経過した時間がミリ秒単位で返されます。この値を使って計算し、求めた値を setTime() を使って日付オブジェクトに適用したり、新しい日付オブジェクトのパラメータとして使用したりできます。

たとえば、次のとおりです。

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var yesterday = new Date(now.getTime() - MILLIS_PER_DAY);

この例では yesterday がちょうど 24 時間前に当たります。

レポート作成

AdWordsApp.report(query, optArgs) を使ってレポートを取得する場合、AdWords クエリ言語(AWQL)で日付を 8 桁の整数(YYYYMMDD)で指定する必要があります。同様に、AdWords スクリプトの多くのオブジェクトで使用できる getStatsFor() メソッドでも、8 桁の整数で日付を指定する必要があります。日付オブジェクトの形式を指定するには、Utilities.formatDate(date, timeZone, format) を使用します。

たとえば、1~3 日前のレポートを取得する場合は次のようになります。

var MILLIS_PER_DAY = 1000 * 60 * 60 * 24;
var now = new Date();
var from = new Date(now.getTime() - 3 * MILLIS_PER_DAY);
var to = new Date(now.getTime() - 1 * MILLIS_PER_DAY);

var timeZone = AdWordsApp.currentAccount().getTimeZone();
var report = AdWordsApp.report(
  'SELECT CampaignName, Clicks ' +
  'FROM   CAMPAIGN_PERFORMANCE_REPORT ' +
  'DURING ' + Utilities.formatDate(from, timeZone, 'yyyyMMdd') + ','
            + Utilities.formatDate(to, timeZone, 'yyyyMMdd'));

スプレッドシート

AdWords スクリプトでは、日付オブジェクトを含むデータをスプレッドシートに出力することがあります。日付オブジェクトをスプレッドシートのセルに含めると、日付の解析にスプレッドシートのタイムゾーンが使用されます。 たとえば、タイムゾーンが太平洋標準時に設定されたスプレッドシートがあるとします。

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

セル A1 に「17-Feb-16 10:00:00」と表示されます。

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

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

または、スプレッドシートのタイムゾーンを手動で設定することもできます

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。