ライブラリ

ライブラリは、他のスクリプトで関数を再利用できるスクリプト プロジェクトです。

ライブラリを使用するスクリプトは、すべてのコードが単一のスクリプト プロジェクトに含まれている場合ほど高速に実行されません。ライブラリを使用すると開発とメンテナンスが便利になりますが、速度が重要なプロジェクトではライブラリの使用を控えてください。この問題のため、Google Workspace アドオンでのライブラリの使用は制限する必要があります。

ライブラリにアクセスする

ライブラリをプロジェクトに含めるには、少なくとも表示レベルのアクセス権が必要です。含めるライブラリの作成者でない場合は、作成者に連絡してアクセス権をリクエストします。

含めるライブラリのスクリプト ID が必要です。ライブラリにアクセスできる場合は、[プロジェクトの設定] ページでスクリプト ID を確認します。

スクリプト プロジェクトにライブラリを追加する

1. Apps Script エディタの左側で、[ライブラリ] の横にある [ライブラリを追加] をクリックします。
2. [スクリプト ID] フィールドに、ライブラリのスクリプト ID を貼り付けます。
3. [Look up] をクリックします。
   エラーが発生した場合は、含めようとしているプロジェクトに対する閲覧者レベル以上のアクセス権があることを確認してください。
4. [バージョン] プルダウンをクリックして、使用するライブラリのバージョンを選択します。
5. デフォルトの「Identifier」名が、このライブラリで使用する名前であることを確認します。これは、スクリプトがライブラリを参照するために使用する名前です。たとえば、Test に設定した場合は、次のようにライブラリのメソッドを呼び出します。Test.libraryMethod。
   MailApp などの既存のサービスの名前や、以前に追加したライブラリの名前と一致する識別子名を使用すると、既存のサービスまたはライブラリが、最近追加したライブラリでオーバーライドされます。
6. [追加] をクリックします。

ライブラリを使用する

デフォルトのサービスを使用する場合と同様に、含まれているライブラリを使用します。たとえば、ライブラリの識別子が Test の場合は、Test の直後にピリオドを入力すると、ライブラリ内のメソッドの一覧が表示されます。

次の手順で、含まれているライブラリのリファレンス ドキュメントを開きます。

スクリプト エディタの左側にあるライブラリ名の横にある [その他] > [新しいタブで開く] をクリックします。

ライブラリを削除する

スクリプト エディタの左側にあるライブラリ名の横にあるその他アイコン > [削除] > [ライブラリを削除] をクリックします。

ライブラリが作成者によって削除された場合でも、含まれているライブラリのリストから削除する必要があります。

ライブラリを更新する

ライブラリのバージョンを変更するか、識別子を更新します。

1. エディタの左側にある [ライブラリ] で、ライブラリの名前をクリックします。
2. 変更を加えて、[保存] をクリックします。

ライブラリを作成して共有する

スクリプト プロジェクトをライブラリとして使用して共有する手順は次のとおりです。

1. スクリプトのバージョン管理されたデプロイを作成します。
2. ライブラリのすべての潜在的なユーザーと、少なくとも閲覧レベルのアクセス権を共有します。
3. これらのユーザーに、[プロジェクトの設定] ページで確認できるスクリプト ID を提供します。

ベスト プラクティス

ライブラリを作成する際のガイドラインは次のとおりです。

1. ライブラリが他のユーザーによって含まれるときにデフォルトの識別子として使用されるため、プロジェクトには意味のある名前を選択してください。
2. スクリプトの 1 つ以上のメソッドをライブラリ ユーザーに表示（使用）しないようにするには、メソッド名の末尾にアンダースコアを付けます。例: myPrivateMethod_
3. ライブラリ ユーザーには、列挙可能なグローバル プロパティのみが表示されます。これには、関数宣言、var を使用して関数の外部で作成された変数、グローバル オブジェクトで明示的に設定されたプロパティが含まれます。たとえば、enumerable を false に設定した Object.defineProperty() は、ライブラリで使用できるシンボルを作成しますが、このシンボルはユーザーがアクセスできません。

4. ライブラリ ユーザーがスクリプト エディタのオートコンプリートと自動生成されたドキュメントを利用できるようにするには、すべての関数に JSDoc スタイルのドキュメントを含めます。次の例をご覧ください。

   /**
    * Raises a number to the given power, and returns the result.
    *
    * @param {number} base the number we're raising to a power
    * @param {number} exp the exponent we're raising the base to
    * @return {number} the result of the exponential calculation
    */
   function power(base, exp) { ... }
   

リソースのスコープ設定

ライブラリを使用する場合、リソースには共有と非共有の 2 種類があります。共有リソースとは、ライブラリとインクルード スクリプトの両方が、リソースの同じインスタンスへの組み込みアクセス権を持っていることを意味します。次の図は、ユーザー プロパティの例を使用して共有リソースを示しています。

共有されないリソースとは、ライブラリとそれを組み込むスクリプトの両方が、リソースのインスタンスへの組み込みアクセス権のみを持つことを意味します。ただし、ライブラリは、共有されていないリソースを操作する明示的な関数を持つことで、それらのリソースへのアクセスを提供できます。ライブラリに含めてスクリプト プロパティを公開する関数の例を次に示します。

  function getLibraryProperty(key) {
    const scriptProperties = PropertiesService.getScriptProperties();
    return scriptProperties.getProperty(key);
  }

次の図は、スクリプト プロパティの例を使用して、共有されていないリソースを示しています。

次の表に、共有リソースと非共有リソースを示します。

リソース	共有*	Not-Shared**	メモ
ロック			ライブラリで作成されたインスタンスは、スクリプトを含め、すべてのユーザーに表示されます。
スクリプト プロパティ			ライブラリで作成されたインスタンスは、スクリプトを含め、すべてのユーザーに表示されます。
キャッシュ			ライブラリで作成されたインスタンスは、スクリプトを含め、すべてのユーザーに表示されます。
トリガー			ライブラリで作成された単純なトリガーは、インクルード スクリプトによってトリガーされません。
ScriptApp
UiApp
ユーザー プロパティ
ロガーと実行トランスクリプト
サイト、スプレッドシート、その他のコンテナ			getActive を呼び出すと、インクルード スクリプトのコンテナが返されます。
MailApp と GmailApp
* これは、ライブラリに機能/リソースの独自のインスタンスがなく、代わりにそれを呼び出したスクリプトによって作成されたインスタンスを使用していることを意味します。 ** これは、ライブラリにリソース/機能の独自のインスタンスがあり、ライブラリを使用するすべてのスクリプトがその同じインスタンスを共有してアクセスできることを意味します。

ライブラリをテストする

ライブラリをテストするには、ヘッド デプロイを使用します。スクリプトに対する編集者レベルのアクセス権を持つユーザーは、ヘッド デプロイを使用できます。

ライブラリのバージョンを少なくとも 1 つ保存する必要があります。

ライブラリをデバッグする

ライブラリを含むスクリプトをデバッグする場合、ライブラリ コードにステップインしたり、ブレークポイントを設定したりすることはできません。デバッグモードでライブラリ関数にステップインしようとすると、デバッガはその関数をスキップして、呼び出しスクリプトの次の行にステップします。

ライブラリ バージョンに HEAD（開発モード）を使用しても、ライブラリへのステップインや、ライブラリ内のブレークポイントへのヒットは有効になりません。

ライブラリ コードをデバッグするには、次のいずれかの方法を使用します。

• ライブラリ プロジェクトからデバッグする: Apps Script エディタでライブラリ スクリプト プロジェクトを開きます。特定の引数を使用してライブラリ関数をテストするには、ライブラリ関数を呼び出す一時的な「テスト」関数をライブラリ プロジェクト内に作成し、そのテスト関数をデバッグモードで実行します。
• ロギング: ライブラリ関数内で console.log() を使用して、実行ログに情報を出力します。ライブラリが別のスクリプトから呼び出されると、これらのログは呼び出し元スクリプトの実行ログに表示されます。