エディタのアドオンの承認

多くの Apps Script ベースのアプリの認証は簡単です。スクリプト プロジェクトは、ユーザーが使用しようとしたときに、不足している権限をリクエストします。

エディタ アドオンの認可モデルは、次の理由でより複雑です。

• ユーザーがファイルを作成すると、ユーザーがインストールしたすべてのアドオンが [拡張機能] メニューに表示されます（ユーザーがまだアドオンを承認していない場合でも表示されます）。

• これらのアドオンは、共同編集者と共有できる Google ドライブ内のファイルで動作します。エディタ アドオンがインストールされていない共同編集者は、ファイル作成者が使用したドキュメントでエディタ アドオンを確認できます。

• エディタ アドオンは、ドキュメントが開くと onOpen() 関数を自動的に実行します。

ユーザーデータを保護するため、onOpen() が一部のサービスを使用できないようにする認可モードが適用されます。このガイドでは、コードが何をいつ実行できるかを理解できます。

認可モデル

エディタ アドオンの承認モードは、その状態によって異なります。状態は、アドオンをインストールしたユーザーか共同編集者かによって異なります。

エディタのアドオンの状態

[拡張機能] メニューのエディタ アドオンがインストールされている、有効になっている、またはその両方である。

• アドオンは、ユーザーまたは管理者が Google Workspace Marketplace から取得し、Google データへのアクセスを許可した後、そのユーザーにインストールされます。
• ドキュメント、フォーム、プレゼンテーション、スプレッドシートでアドオンが有効になっている場合、そのアドオンは誰でも使用できます。
• 複数のユーザーがファイルを共同編集していて、そのうちの 1 人がアドオンを使用している場合、そのアドオンは 1 人のユーザーに対してインストールされ、ファイルに対して有効になります。

次の表に、インストール済みと有効の違いを示します。スクリプトをアドオンとしてテストする場合は、これらの状態のいずれかまたは両方でテストを実行できます。

	インストール済み	有効
適用対象	ユーザー	ドキュメント、フォーム、プレゼンテーション、スプレッドシート
原因	ストアからアドオンを入手する	ドキュメント、フォーム、プレゼンテーション、スプレッドシートの使用中にストアからアドオンを取得する、または 以前にインストールしたアドオンをドキュメント、フォーム、プレゼンテーション、スプレッドシートで使用する
メニューを表示できるユーザー	開いたまたは作成したすべてのドキュメント、フォーム、プレゼンテーション、スプレッドシートで、そのユーザーのみ	そのドキュメント、フォーム、プレゼンテーション、スプレッドシートのすべての共同編集者
onOpen() の認可モード	AuthMode.NONE （有効になっている場合を除く。その場合は AuthMode.LIMITED)）	AuthMode.LIMITED

認可モード

エディタ アドオンの onOpen() 関数は、ユーザーがドキュメント、フォーム、プレゼンテーション、スプレッドシートを開いたときに自動的に実行されます。ユーザーのデータを保護するため、Apps Script では onOpen() 関数の実行内容が制限されています。onOpen() 関数が実行される認可モードは、エディタ アドオンの状態によって決まります。

ファイル、フォーム、プレゼンテーション、スプレッドシートでエディタ アドオンが有効になっている場合、onOpen() は AuthMode.LIMITED で実行されます。アドオンが有効ではなく、インストールされているだけの場合は、onOpen() は AuthMode.NONE で実行されます。

AuthMode.NONE では、ユーザーがカスタム関数をクリックまたは実行してアドオンを操作するまで、アドオンは特定のサービスを実行できません。アドオンが onOpen()、onInstall()、またはグローバル スコープでこれらのサービスを使用しようとすると、権限が失敗し、メニューの入力などの他の呼び出しが停止します。サポートされているオプションは「ヘルプ」のみです。

制限付きサービス呼び出しを実行するには、AuthMode.FULL 承認モードを使用する必要があります。メニュー オプションのクリックなど、ユーザー操作関数は、このモードでのみ実行されます。コードが AuthMode.FULL モードで実行されると、アドオンはユーザーが承認したすべてのスコープを使用できるようになります。

注: AuthMode.NONE に配置できるのは、公開済みの Editor アドオンのみです。公開されていない Editor アドオンは、AuthMode.LIMITED で onOpen() を実行します。ただし、エディタ アドオンをテストして、開発中のアドオンがどちらの承認モードでも意図したとおりに動作することを確認できます。

Apps Script は、認可モードを Apps Script のイベント パラメータ e の authMode プロパティとして渡します。e.authMode の値は、Apps Script の ScriptApp.AuthMode 列挙型の定数に対応しています。

認可モードは、スクリプト エディタ、メニュー項目、Apps Script の google.script.run 呼び出しからの実行など、すべての Apps Script 実行方法に適用されます。ただし、e.authMode プロパティを検査できるのは、onOpen()、onEdit()、onInstall() などのトリガーの結果としてスクリプトが実行された場合のみです。Google スプレッドシートのカスタム関数は、独自の認可モード AuthMode.CUSTOM_FUNCTION を使用します。これは LIMITED に似ていますが、制限が若干異なります。その他のすべてのケースでは、次の表に示すように、スクリプトは AuthMode.FULL で実行されます。

	NONE	LIMITED	CUSTOM_FUNCTION	FULL
発生する対象	onOpen()（ユーザーがアドオンをインストールしたが、ドキュメント、フォーム、プレゼンテーション、スプレッドシートで有効にしていない場合）	onOpen()（それ以外の時間） onEdit()（スプレッドシートのみ）	カスタム関数	その他のすべてのタイミング（以下を含む）: インストール可能なトリガー onInstall() google.script.run
ユーザーデータへのアクセス	ロケールのみ	ロケールのみ	ロケールのみ	はい
ドキュメント、フォーム、プレゼンテーション、スプレッドシートへのアクセス	いいえ	はい	はい - 読み取り専用	はい
管理画面へのアクセス	メニュー アイテムを追加する	メニュー アイテムを追加する	いいえ	はい
Properties へのアクセス	いいえ	○	○	はい
Jdbc、UrlFetch へのアクセス	いいえ	×	○	はい
その他のサービス	Logger Utilities	ユーザーデータにアクセスしないサービス	ユーザーデータにアクセスしないサービス	すべてのサービス

エディタ アドオンの承認ライフサイクル

現在のユーザー用にアドオンがインストールされているか、現在のファイルで有効になっている場合、そのファイルが開かれると、ドキュメント、フォーム、プレゼンテーション、スプレッドシートにアドオンが読み込まれます。アドオンは [拡張機能] メニューに表示され、シンプル トリガー onInstall()、onOpen()、onEdit() のリッスンを開始します。ユーザーが [拡張機能] メニュー項目をクリックすると、拡張機能が実行されます。

エディタのアドオンがインストールされている

ストアからエディタ アドオンをインストールすると、その onInstall() 関数は AuthMode.FULL で実行されます。この承認モードでは、アドオンは複雑な設定ルーティンを実行できます。また、ドキュメント、フォーム、プレゼンテーション、スプレッドシートはすでに開いており、onOpen() 関数は実行されていないため、onInstall() を使用してメニュー アイテムを作成する必要があります。次のサンプルは、onInstall() 関数から onOpen() 関数を呼び出す方法を示しています。

function onInstall(e) {
  onOpen(e);
  // Perform additional setup as needed.
}

エディタのアドオンが開きます

ドキュメント、フォーム、プレゼンテーション、スプレッドシートを開くと、現在のユーザーがインストールしたエディタ アドオンや、共同編集者がファイルで有効にしたエディタ アドオンがすべて読み込まれ、それぞれの onOpen() 関数が呼び出されます。onOpen() が実行される認可モードは、アドオンがインストールされているか有効かによって異なります。

アドオンが基本的なメニューのみを作成する場合は、モードは重要ではありません。次のサンプルは、基本的な onOpen() 関数を示しています。

function onOpen(e) {
  SpreadsheetApp.getUi().createAddonMenu() // Or DocumentApp.
      .addItem('Insert chart', 'insertChart')
      .addItem('Update charts', 'updateCharts')
      .addToUi();
}

保存されている Apps Script のプロパティに基づいて動的メニュー アイテムを追加したり、現在のファイルの内容を読み取ったり、その他の高度なタスクを実行したりするには、認可モードを特定して適切に処理する必要があります。

次のサンプルは、認可モードに基づいてアクションを変更する高度な onOpen() 関数を示しています。

function onOpen(e) {
  var menu = SpreadsheetApp.getUi().createAddonMenu(); // Or DocumentApp.
  if (e && e.authMode == ScriptApp.AuthMode.NONE) {
    // Add a normal menu item (works in all authorization modes).
    menu.addItem('Start workflow', 'startWorkflow');
  } else {
    // Add a menu item based on properties (doesn't work in AuthMode.NONE).
    var properties = PropertiesService.getDocumentProperties();
    var workflowStarted = properties.getProperty('workflowStarted');
    if (workflowStarted) {
      menu.addItem('Check workflow status', 'checkWorkflow');
    } else {
      menu.addItem('Start workflow', 'startWorkflow');
    }
  }
  menu.addToUi();
}

警告: onOpen() 関数が実行されると、スクリプト全体が読み込まれ、すべてのグローバル ステートメントが onOpen() と同じ認可モードで実行されます。認可モードでグローバル ステートメントが禁止されている場合、グローバル ステートメントと onOpen() の両方が実行されません。公開されたアドオンでメニュー項目が追加されない場合は、ブラウザの JavaScript コンソールでエラーが返されたかどうかを確認します。次に、スクリプトを確認して、onOpen() 関数またはグローバル変数が AuthMode.NONE で許可されていないサービスを呼び出していないか確認します。

AuthMode.LIMITED で実行中にアドオンがサイドバーやダイアログを開くことはできません。サイドバーとダイアログは AuthMode.FULL で実行されるため、メニュー項目を使用して開くことができます。

ユーザーがエディタ アドオンを実行する

ユーザーが [拡張機能] メニュー項目をクリックすると、Apps Script はまずユーザーがアドオンをインストールしているかどうかを確認し、インストールしていない場合はインストールするよう促します。ユーザーがアドオンを承認すると、スクリプトは AuthMode.FULL のメニュー項目に対応する関数を実行します。ドキュメント、フォーム、プレゼンテーション、スプレッドシートでアドオンが有効になります（まだ有効になっていない場合）。

アドオン メニューが表示されない場合のトラブルシューティング

コードで認可モードが正しく管理されていない場合、アドオン メニューがレンダリングされないことがあります。次に例を示します。

• アドオンが、現在の認可モードでサポートされていない Apps Script サービスを実行しようとしています。

• アドオンが、ユーザーが操作する前にサービス呼び出しを実行しようとしている。

AuthMode.NONE で権限エラーの原因となっているサービス呼び出しを削除または並べ替えるには、次の操作を試してください。

1. アドオンの Apps Script プロジェクトを開き、onOpen() 関数を見つけます。
2. onOpen() 関数で、Apps Script サービスやそれに関連するオブジェクト（PropertiesService、SpreadsheetApp、GmailApp など）の記述を検索します。
3. サービスが UI 要素の作成以外の目的で使用されている場合は、削除するか、コメント ブロックでラップします。残すメソッドは .getUi()、.createMenu()、.addItem()、.addToUi() のみです。また、関数外のサービスを探して削除します。
4. 前の手順でコメント化または削除されたコード行が含まれている可能性のある関数（特に、生成された情報を使用している関数）を特定し、サービス呼び出しを必要とする関数に移動します。前の手順で行った変更に対応するように、コードベースを再編成または書き換えます。

5. コードを保存して、テスト用のデプロイメントを作成します。

   テスト用デプロイメントを作成するときに、[Config] フィールドが [Installed for current user] になっていること、[Config] ボックスの下のテキストが [Test in AuthMode.None] になっていることを確認します。

6. テスト環境を起動し、[Extensions] メニューを開きます。

7. すべてのメニュー項目が表示されたら、問題は解決しています。[ヘルプ] メニューのみが表示される場合は、ステップ 1 に戻ります。サービス コールを見逃した可能性があります。

関連トピック

• ウェブアプリ
• アドオンの種類
• エディタ用アドオンをテストする