Google Apps Scriptで時間トリガーが使用している関数の合計実行時間が知りたい

# 背景と問題点
Google Apps Scriptでは時間トリガーを設定して定期的に関数を実行させることができます。例えば、10分毎に``myFunction()``を実行させることができるようになっています。ただし、それぞれのアカウントで1日に使用できる時間トリガーの合計実行時間が決まっています。[Quotas for Google Services](https://developers.google.com/apps-script/guides/services/quotas)を見ると、多くのユーザが利用していると思われるConsumerアカウントの場合、90 min / dayの制限が設けられています。例えば2つの関数を時間トリガーで使用していると、それらの合計が1日当たり90分を超えるとエラーが発生し、quotaがリセットされるまでの間、それ以上の実行はできなくなってしまいます。このため、時間トリガーで実行中の各関数の合計実行時間を取得することは重要と思われます。

私自身、これまでは時間トリガーで使用する全ての各関数に合計実行時間を記録するメソッドを追加することで回避策としていました。しかし、この回避策では本当に実行したい内容に加えて時間を記録するためのコストも同時に含まれてしまう欠点がありました。

# 解決方法
公式の方法でこのような合計時間を取得することができないものかと考えていた時、[Apps Script APIのprocesses.listメソッド](https://developers.google.com/apps-script/api/reference/rest/v1/processes/list)がこれを解決するのではないかとの結論に至りました。実際に実装して実験を行った結果、実用的であることが分かりましたので公開させていただきました。

Apps Script APIのprocesses.listメソッドは、アカウント内で実行している全ての関数の情報を取得することができます。これをフィルタを使用することで時間トリガーの情報のみを取得し、これらのduration timeを合計することで時間トリガーが使用している合計実行時間を取得します。

Apps Script APIを使用することで実現できますので、スクリプトを用意することでGoogle Apps Script以外で外部からこのような情報を取得することも可能です。

# ライブラリ
[ユーザ側でのスコープ設定を省略するためにライブラリとして公開](https://qiita.com/tanaike/items/6488f755f742c9031e73)させていただきました。リポジトリは[こちら](https://github.com/tanaikech/ProcessApp)です。

## ライブラリのインストール
1. スクリプトエディタを起動
1. リソース -> ライブラリ を選択
1. ライブラリの追加でライブラリのプロジェクトキーを入力し、追加ボタンを押します。
	- ライブラリのプロジェクトキーは、``1y3BjeYyJUdI9U2JZ97POIXRTaYnjsbH6SUapd43s8S8vh2Io5pho6xZ6``です。
1. 「ProcessApp」のライブラリが表示されるのを確認し、バージョンを最新のものへ、デベロッパーモードを「有効」にします。
1. 「保存」ボタンを押して設定を保存します。

## Apps Script Apiの有効化
次にAPIコンソールでApps Script APIを有効にします。

1. スクリプトエディタの「リソース」 -> 「Cloud Platformプロジェクト」を開きます。
1. 「このスクリプトが現在関連付けられているプロジェクト:」の下のリンクをクリックします。
1. 「スタートガイド」の「APIを探索して有効にする」をクリックします。
1. 左側のサイドバーにある「ライブラリ」をクリックします。
1. 「APIとサービスを検索」へ 「Apps Script」 と入力して検索します。
1. 表示された中からApps Script APIをクリックします。
1. Apps Script APIを有効にします。ボタンをクリックしてから少しの待ち時間があります。
	- 有効にしてすぐにスクリプトを実行するとエラーが発生する場合は、少し時間をおいてから再度実行してみてください。

# 使用方法
デフォルト設定として、スクリプトを実行した時間から24時間前の間で時間トリガーで実行されている全ての関数の合計実行時間を取得するには次のスクリプトを使用します。

~~~javascript
var res = ProcessApp.getExecutionTimeOfTrigger();
~~~

もしも、特定のプロジェクトで特定の関数、特定の期間内の合計実行時間を取得したい場合は、オブジェクトとして下記のように与えることで結果を取得することができます。

~~~javascript
var object = {
    projectId: "#####", // Project ID
    functionName: "myFunction1", // function name that you want to know the total execution time.
    startTime: "2019-02-01T00:00:00.000Z",
    endTime: "2019-02-02T00:00:00.000Z",
};
var res = ProcessApp.getExecutionTimeOfTrigger(object);
~~~

- ``startTime``と``endTime``は、次のように定義されています。
	- A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z". [Ref](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp)

# 結果
例えば``myFunction1``と``myFunction2``の2つの関数が時間トリガーとして動作している場合、下記のような結果が返されます。この場合、``myFunction1``と``myFunction2``のそれぞれの合計実行時間は、1200秒、180秒で、それらの合計は``statistics``で1380秒として見ることができます。

~~~
{
  "statistics": {
    "allFunctions": [
      "myFunction1",
      "myFunction2"
    ],
    "totalExecutionTimeSec": 1380.00,
    "totalExecutionTimeMin": 23.00
  },
  "eachFunction": [
    {
      "functionName": "myFunction1",
      "totalExecutionTimeSec": 1200.00,
      "totalExecutionTimeMin": 20.00
    },
    {
      "functionName": "myFunction2",
      "totalExecutionTimeSec": 180.00,
      "totalExecutionTimeMin": 3.00
    }
  ]
}
~~~

# 参考
- [processes.list](https://developers.google.com/apps-script/api/reference/rest/v1/processes/list)

このような方法がお役に立ちましたら幸いです。