ライブラリ

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

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

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

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

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

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

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

ライブラリを使用する

デフォルトのサービスを使用するように、付属のライブラリを使用します。たとえば、ライブラリの ID が Test の場合は、Test の直後にピリオドを入力して、ライブラリ内のメソッドのリストを表示します。

含まれるライブラリのリファレンス ドキュメントを開く手順は次のとおりです。

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

ライブラリを削除する

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

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

ライブラリを更新する

ライブラリのバージョンを変更したり、ID を更新したりできます。

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

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

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

1. スクリプトのバージョニングされた Deployment を作成します。
2. ライブラリのすべてのユーザー候補と少なくとも閲覧レベルのアクセス権を共有します。
3. スクリプト ID をユーザーに伝えます。スクリプト ID は、[プロジェクト設定] の ページで確認できます。

ベスト プラクティス

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

1. ライブラリが他のユーザーによって含められるときにデフォルトの ID として使用されるため、プロジェクトに意味のある名前を選択します。
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);
  }

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

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

リソース	共有*	共有なし**	メモ
ロック			ライブラリで作成された場合、同じインスタンスがスクリプトを含むすべてのユーザーに表示されます。
スクリプト プロパティ			ライブラリで作成された場合、同じインスタンスがスクリプトを含むすべてのユーザーに表示されます。
キャッシュ			ライブラリで作成された場合、同じインスタンスがスクリプトを含むすべてのユーザーに表示されます。
トリガー			ライブラリで作成された単純なトリガーは、含めるスクリプトによってトリガーされません。
ScriptApp
UiApp
ユーザー プロパティ
ロガーと実行トランスクリプト
サイト、シート、その他のコンテナ			getActive() を呼び出すと、包含スクリプトのコンテナが返されます。
MailApp と GmailApp
* つまり、ライブラリには特徴/リソースの独自のインスタンスが存在せず、呼び出したスクリプトによって作成されたインスタンスが使用されます。 ** つまり、ライブラリにはリソース/機能の独自のインスタンスが存在し、ライブラリを使用するすべてのスクリプトがその同じインスタンスを共有してアクセスできます。

ライブラリをテストする

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

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

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

ライブラリを含むプロジェクトでデバッガを使用すると、ライブラリの関数にステップインできます。コードがデバッガに表示されます。表示モードは「表示のみ」で、バージョンは正しいものです。