スクリプトの V8 ランタイムへの移行

Rhino ランタイムを使用する既存のスクリプトがあり、V8 の構文と機能を使用する場合は、スクリプトを V8 に移行する必要があります。

Rhino ランタイムを使用して記述したスクリプトのほとんどは、V8 ランタイムを使用しても調整なしで動作します。多くの場合、スクリプトに V8 の構文と機能を追加するための唯一の前提条件は、V8 ランタイムを有効にすることです。

ただし、少数の非互換性やその他の相違点があるため、V8 ランタイムを有効にした後、スクリプトのエラーや予期しない動作が発生する可能性があります。V8 を使用するようにスクリプトを移行する場合は、スクリプト プロジェクトでこれらの問題を検索し、見つかった場合は修正する必要があります。

V8 の移行手順

スクリプトを V8 に移行する手順は次のとおりです。

  1. スクリプトで V8 ランタイムを有効にします。
  2. 下記の非互換性を慎重に確認してください。スクリプトを調べて、互換性の問題があるかどうかを確認します。互換性の問題がある場合は、スクリプト コードを調整して、問題を解消するか、問題を回避します。
  3. 下記のその他の違いをよくご確認ください。 スクリプトを調べて、リストされている相違点のいずれかがコードの動作に影響するかどうかを確認します。スクリプトを調整して動作を修正します。
  4. 検出された非互換性やその他の相違点を修正したら、必要に応じて V8 構文とその他の機能を使用するようにコードを更新できます。
  5. コードの調整が完了したら、スクリプトを十分にテストして、想定どおりに動作することを確認します。
  6. スクリプトがウェブアプリまたは公開されているアドオンの場合は、V8 を調整した新しいバージョンのスクリプトを作成する必要があります。ユーザーが V8 バージョンを使用できるようにするには、このバージョンでスクリプトを再公開する必要があります。

非互換性

残念ながら、元の Rhino ベースの Apps Script ランタイムでは、標準ではない ECMAScript の動作がいくつか許可されていました。V8 は標準に準拠しているため、移行後はこの動作はサポートされません。これらの問題を修正しないと、V8 ランタイムが有効になったときに、エラーが発生したり、スクリプトの動作が壊れたりします。

以降のセクションでは、こうした各動作と、V8 への移行時にスクリプト コードを修正するために必要な手順について説明します。

for each(variable in object) を避ける

JavaScript 1.6 には for each (variable in object) ステートメントが追加され、for...of に置き換えられたため削除されました。

スクリプトを V8 に移行する場合は、for each (variable in object) ステートメントを使用しないでください。

代わりに for (variable in object) を使用します。

// Rhino runtime
var obj = {a: 1, b: 2, c: 3};

// Don't use 'for each' in V8
for each (var value in obj) {
  Logger.log("value = %s", value);
}
      
// V8 runtime
var obj = {a: 1, b: 2, c: 3};

for (var key in obj) {  // OK in V8
  var value = obj[key];
  Logger.log("value = %s", value);
}

Date.prototype.getYear() を避ける

元の Rhino ランタイムでは、Date.prototype.getYear() は 1900 ～ 1999 年については 2 桁の年を返しますが、他の日付については 4 桁の年を返します。これは JavaScript 1.2 以前の動作でした。

V8 ランタイムでは、Date.prototype.getYear() は ECMAScript 標準の要件に従って、代わりに 1900 年を引いた年を返します。

スクリプトを V8 に移行する場合は、必ず Date.prototype.getFullYear() を使用してください。これにより、日付に関係なく 4 桁の年が返されます。

予約済みキーワードを名前として使用しない

ECMAScript では、関数名と変数名に特定の予約済みキーワードは使用できません。Rhino ランタイムでは、これらの単語の多くが許可されているため、コードでこれらの単語を使用する場合は、関数または変数の名前を変更する必要があります。

スクリプトを V8 に移行する場合は、予約済みキーワードのいずれかを使用して変数または関数に名前を付けることは避けてください。キーワード名が使用されないように、変数または関数の名前を変更します。キーワードを名前としてよく使用するのは、class、import、export です。

const 変数の再代入を回避する

元の Rhino ランタイムでは、const を使用して変数を宣言できます。つまり、シンボルの値は変更されず、シンボルへの今後の割り当ては無視されます。

新しい V8 ランタイムでは、const キーワードは標準に準拠しており、const として宣言された変数に代入すると、TypeError: Assignment to constant variable ランタイム エラーが発生します。

スクリプトを V8 に移行する場合は、const 変数の値を再割り当てしようとしないでください。

// Rhino runtime
const x = 1;
x = 2;          // No error
console.log(x); // Outputs 1
      
// V8 runtime
const x = 1;
x = 2;          // Throws TypeError
console.log(x); // Never executed

XML リテラルと XML オブジェクトを避ける

この ECMAScript の非標準の拡張により、Apps Script プロジェクトで XML 構文を直接使用できるようになります。

スクリプトを V8 に移行する場合は、XML リテラルや XML オブジェクトを直接使用しないでください。

代わりに、XmlService を使用して XML を解析します。

// V8 runtime
var incompatibleXml1 = <container><item/></container>;             // Don't use
var incompatibleXml2 = new XML('<container><item/></container>');  // Don't use

var xml3 = XmlService.parse('<container><item/></container>');     // OK

__iterator__ を使用してカスタム イテレータ関数を作成しない

JavaScript 1.7 では、クラスのプロトタイプで __iterator__ 関数を宣言することで任意のクラスにカスタム イテレータを追加できる機能が追加されました。これは開発者の便宜上、Apps Script の Rhino ランタイムにも追加されました。ただし、この機能は ECMA-262 標準には含まれておらず、ECMAScript 準拠の JavaScript エンジンで削除されました。V8 を使用するスクリプトでは、このイテレータ構造を使用できません。

スクリプトを V8 に移行する場合は、カスタム イテレータをビルドする際に __iterator__ 関数を使用しないようにします。代わりに、ECMAScript 6 のイテレータを使用してください。

次の配列構成について考えてみましょう。

// Create a sample array
var myArray = ['a', 'b', 'c'];
// Add a property to the array
myArray.foo = 'bar';

// The default behavior for an array is to return keys of all properties,
//  including 'foo'.
Logger.log("Normal for...in loop:");
for (var item in myArray) {
  Logger.log(item);            // Logs 0, 1, 2, foo
}

// To only log the array values with `for..in`, a custom iterator can be used.

次のコードサンプルは、Rhino ランタイムでイテレータを作成する方法と、V8 ランタイムで置換イテレータを作成する方法を示しています。

// Rhino runtime custom iterator
function ArrayIterator(array) {
  this.array = array;
  this.currentIndex = 0;
}

ArrayIterator.prototype.next = function() {
  if (this.currentIndex
      >= this.array.length) {
    throw StopIteration;
  }
  return "[" + this.currentIndex
    + "]=" + this.array[this.currentIndex++];
};

// Direct myArray to use the custom iterator
myArray.__iterator__ = function() {
  return new ArrayIterator(this);
}


Logger.log("With custom Rhino iterator:");
for (var item in myArray) {
  // Logs [0]=a, [1]=b, [2]=c
  Logger.log(item);
}
      
// V8 runtime (ECMAScript 6) custom iterator
myArray[Symbol.iterator] = function() {
  var currentIndex = 0;
  var array = this;

  return {
    next: function() {
      if (currentIndex < array.length) {
        return {
          value: "[${currentIndex}]="
            + array[currentIndex++],
          done: false};
      } else {
        return {done: true};
      }
    }
  };
}

Logger.log("With V8 custom iterator:");
// Must use for...of since
//   for...in doesn't expect an iterable.
for (var item of myArray) {
  // Logs [0]=a, [1]=b, [2]=c
  Logger.log(item);
}

条件付き catch 句を使用しない

V8 ランタイムは、標準に準拠していないため、catch..if 条件付きキャッチ句をサポートしていません。

スクリプトを V8 に移行する場合は、キャッチ条件をキャッチ本文内に移動してください。

// Rhino runtime

try {
  doSomething();
} catch (e if e instanceof TypeError) {  // Don't use
  // Handle exception
}
      
// V8 runtime
try {
  doSomething();
} catch (e) {
  if (e instanceof TypeError) {
    // Handle exception
  }
}

Object.prototype.toSource() を使用しない

JavaScript 1.3 には、ECMAScript 標準に含まれていなかった Object.prototype.toSource() メソッドが含まれていました。V8 ランタイムではサポートされていません。

スクリプトを V8 に移行する場合は、コードから Object.prototype.toSource() の使用をすべて削除してください。

その他の相違点

スクリプトを失敗させる原因となる上記の非互換性のほかにも、修正しないと V8 ランタイム スクリプトの予期しない動作を引き起こす違いがいくつかあります。

以降のセクションでは、このような予期せぬ事態を避けるために、スクリプト コードを更新する方法について説明します。

ロケール固有の日付と時刻の形式を調整する

Date メソッドの toLocaleString()、toLocaleDateString()、toLocaleTimeString() の動作は、Rhino と V8 ランタイムでは異なります。

Rhino のデフォルトの形式は「long 形式」であり、渡されたパラメータはすべて無視されます。

V8 ランタイムでは、デフォルトの形式は短い形式になり、渡されるパラメータは ECMA 標準に従って処理されます（詳しくは、toLocaleDateString() のドキュメントをご覧ください）。

スクリプトを V8 に移行する場合は、ロケール固有の日時メソッドの出力に関して、コードが想定どおりであることをテストし、調整します。

// Rhino runtime
var event = new Date(
  Date.UTC(2012, 11, 21, 12));

// Outputs "December 21, 2012" in Rhino
console.log(event.toLocaleDateString());

// Also outputs "December 21, 2012",
//  ignoring the parameters passed in.
console.log(event.toLocaleDateString(
    'de-DE',
    { year: 'numeric',
      month: 'long',
      day: 'numeric' }));
 
// V8 runtime
var event = new Date(
  Date.UTC(2012, 11, 21, 12));

// Outputs "12/21/2012" in V8
console.log(event.toLocaleDateString());

// Outputs "21. Dezember 2012"
console.log(event.toLocaleDateString(
    'de-DE',
    { year: 'numeric',
      month: 'long',
      day: 'numeric' }));

Error.fileName と Error.lineNumber を使用しない

V8 の untime では、標準の JavaScript Error オブジェクトは、コンストラクタ パラメータやオブジェクト プロパティとして fileName または lineNumber をサポートしていません。

スクリプトを V8 に移行する場合は、Error.fileName と Error.lineNumber への依存をすべて削除します。

別の方法として、Error.prototype.stack を使用することもできます。このスタックも標準ではありませんが、Rhino と V8 の両方でサポートされています。2 つのプラットフォームによって生成されるスタック トレースの形式は、若干異なります。

// Rhino runtime Error.prototype.stack
// stack trace format
at filename:92 (innerFunction)
at filename:97 (outerFunction)



// V8 runtime Error.prototype.stack
// stack trace format
Error: error message
at innerFunction (filename:92:11)
at outerFunction (filename:97:5)

文字列化された列挙型オブジェクトの処理を調整

元の Rhino ランタイムでは、列挙型オブジェクトで JavaScript JSON.stringify() メソッドを使用しても {} のみが返されます。

V8 では、列挙型オブジェクトに対して同じメソッドを使用すると、列挙型名が返されます。

スクリプトを V8 に移行する場合は、列挙型オブジェクトでの JSON.stringify() の出力に関するコードの想定をテストし、調整します。

// Rhino runtime
var enumName =
  JSON.stringify(Charts.ChartType.BUBBLE);

// enumName evaluates to {}
 
// V8 runtime
var enumName =
  JSON.stringify(Charts.ChartType.BUBBLE);

// enumName evaluates to "BUBBLE"

未定義パラメータの処理を調整

元の Rhino ランタイムでは、パラメータとして undefined をメソッドに渡すと、そのメソッドに文字列 "undefined" が渡されていました。

V8 では、undefined をメソッドに渡すことは、null を渡した場合と同じです。

スクリプトを V8 に移行する場合は、undefined パラメータに関するコードの想定をテストし、調整します。

// Rhino runtime
SpreadsheetApp.getActiveRange()
    .setValue(undefined);

// The active range now has the string
// "undefined"  as its value.
      
// V8 runtime
SpreadsheetApp.getActiveRange()
    .setValue(undefined);

// The active range now has no content, as
// setValue(null) removes content from
// ranges.

グローバル this の処理を調整

Rhino ランタイムでは、それを使用するスクリプト用に暗黙的な特別なコンテキストが定義されています。スクリプトコードは、実際のグローバル this とは異なる暗黙的なコンテキストで実行されます。つまり、コード内の「グローバル this」への参照は、スクリプトで定義されたコードと変数のみを含む特別なコンテキストを実際に評価します。組み込みの Apps Script サービスと ECMAScript オブジェクトは、この this の使用から除外されます。この状況は、次のような JavaScript 構造でした。

// Rhino runtime

// Apps Script built-in services defined here, in the actual global context.
var SpreadsheetApp = {
  openById: function() { ... }
  getActive: function() { ... }
  // etc.
};

function() {
  // Implicit special context; all your code goes here. If the global this
  // is referenced in your code, it only contains elements from this context.

  // Any global variables you defined.
  var x = 42;

  // Your script functions.
  function myFunction() {
    ...
  }
  // End of your code.
}();

V8 では、暗黙的な特殊なコンテキストは削除されます。スクリプトで定義されたグローバル変数と関数は、Apps Script 組み込みサービスと ECMAScript 組み込み（Math や Date など）と並んで、グローバル コンテキストに配置されます。

スクリプトを V8 に移行する場合は、グローバル コンテキストでの this の使用に関するコードの想定をテストして調整します。ほとんどの場合、コードがグローバル this オブジェクトのキーまたはプロパティ名を調べる場合にのみ、違いは明らかです。

// Rhino runtime
var myGlobal = 5;

function myFunction() {

  // Only logs [myFunction, myGlobal];
  console.log(Object.keys(this));

  // Only logs [myFunction, myGlobal];
  console.log(
    Object.getOwnPropertyNames(this));
}





      
// V8 runtime
var myGlobal = 5;

function myFunction() {

  // Logs an array that includes the names
  // of Apps Script services
  // (CalendarApp, GmailApp, etc.) in
  // addition to myFunction and myGlobal.
  console.log(Object.keys(this));

  // Logs an array that includes the same
  // values as above, and also includes
  // ECMAScript built-ins like Math, Date,
  // and Object.
  console.log(
    Object.getOwnPropertyNames(this));
}

ライブラリ内の instanceof の処理を調整

別のプロジェクトの関数でパラメータとして渡されるオブジェクトのライブラリで instanceof を使用すると、偽陰性が発生する可能性があります。V8 ランタイムでは、プロジェクトとそのライブラリが異なる実行コンテキストで実行されるため、グローバル チェーンとプロトタイプ チェーンも異なります。

これは、ライブラリが、プロジェクト内に作成されていないオブジェクトに instanceof を使用する場合にのみ該当します。プロジェクト内で作成されたオブジェクトに対して使用した場合、プロジェクト内の同じスクリプトまたは別のスクリプトで想定どおりに機能します。

V8 で実行されているプロジェクトでスクリプトがライブラリとして使用されている場合は、別のプロジェクトから渡されるパラメータにスクリプトが instanceof を使用しているかどうかを確認します。instanceof の使用方法を調整し、ユースケースに応じて他の適切な代替手段を使用してください。

a instanceof b の代替策の一つとして、プロトタイプ チェーン全体を検索する必要がなく、コンストラクタを確認するだけの場合に、a のコンストラクタを使用できます。使用方法: a.constructor.name == "b"

プロジェクト A とプロジェクト B で、プロジェクト A がプロジェクト B をライブラリとして使用するとします。

//Rhino runtime

//Project A

function caller() {
   var date = new Date();
   // Returns true
   return B.callee(date);
}

//Project B

function callee(date) {
   // Returns true
   return(date instanceof Date);
}

      
//V8 runtime

//Project A

function caller() {
   var date = new Date();
   // Returns false
   return B.callee(date);
}

//Project B

function callee(date) {
   // Incorrectly returns false
   return(date instanceof Date);
   // Consider using return (date.constructor.name ==
   // “Date”) instead.
   // return (date.constructor.name == “Date”) -> Returns
   // true
}

別の方法として、メイン プロジェクトで instanceof をチェックする関数を導入し、ライブラリ関数を呼び出すときに他のパラメータに加えてその関数を渡すという方法もあります。渡された関数を使用して、ライブラリ内の instanceof をチェックできます。

//V8 runtime

//Project A

function caller() {
   var date = new Date();
   // Returns True
   return B.callee(date, date => date instanceof Date);
}

//Project B

function callee(date, checkInstanceOf) {
  // Returns True
  return checkInstanceOf(date);
}

非共有リソースのライブラリへの受け渡しを調整

非共有リソースをメイン スクリプトからライブラリに渡す方法は、V8 ランタイムでは異なります。

Rhino ランタイムでは、共有されていないリソースを渡しても機能しません。ライブラリは代わりに独自のリソースを使用します。

V8 ランタイムでは、非共有リソースをライブラリに渡しても機能します。ライブラリは、渡された非共有リソースを使用します。

非共有リソースを関数パラメータとして渡さないでください。非共有リソースは常に、それを使用する同じスクリプトで宣言します。

プロジェクト A とプロジェクト B で、プロジェクト A がプロジェクト B をライブラリとして使用するとします。この例では、PropertiesService は非共有リソースです。

// Rhino runtime
// Project A
function testPassingNonSharedProperties() {
  PropertiesService.getScriptProperties()
      .setProperty('project', 'Project-A');
  B.setScriptProperties();
  // Prints: Project-B
  Logger.log(B.getScriptProperties(
      PropertiesService, 'project'));
}



//Project B
function setScriptProperties() {
  PropertiesService.getScriptProperties()
      .setProperty('project', 'Project-B');
}
function getScriptProperties(
    propertiesService, key) {
  return propertiesService.getScriptProperties()
      .getProperty(key);
}

// V8 runtime
// Project A
function testPassingNonSharedProperties() {
  PropertiesService.getScriptProperties()
      .setProperty('project', 'Project-A');
  B.setScriptProperties();
  // Prints: Project-A
  Logger.log(B.getScriptProperties(
      PropertiesService, 'project'));
}



// Project B
function setProperties() {
  PropertiesService.getScriptProperties()
        .setProperty('project', 'Project-B');
}
function getScriptProperties(
    propertiesService, key) {
  return propertiesService.getScriptProperties()
      .getProperty(key);
}

スタンドアロン スクリプトへのアクセス権を更新する

V8 ランタイムで実行されるスタンドアロン スクリプトの場合、スクリプトのトリガーを正常に機能させるには、少なくともスクリプトの表示アクセス権をユーザーに付与する必要があります。