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

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

エディタ用アドオンの承認モデルは、いくつかの理由で複雑になっています。

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

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

• ドキュメントが開くと、エディタ用アドオンの onOpen 関数が自動的に実行されます。

ユーザーデータを保護するため、一部のサービスを onOpen で使用できないようにする承認モードが適用されます。このガイドでは、コードで実行できることとそのタイミングについて説明します。

承認モデル

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

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

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

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

次の表に、インストール済みと有効の違いをまとめます。 スクリプトをアドオンとして テストする場合は、 どちらの状態でもテストを実行できます。

承認モード

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

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

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

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

公開済み のエディタ用アドオンのみがAuthMode.NONEにできます。 未公開 のエディタ用アドオンは、AuthMode.LIMITEDでonOpenを実行します。ただし、どちらの承認モードでも想定されています。これを行うには、 エディタ用アドオンをテストします。

Apps Script は、承認モードを Apps Script イベント パラメータ の authMode プロパティとして渡しますe。 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 で実行されます。

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

現在のアドオンがインストールされているか、現在のファイルで有効になっている場合、そのファイルが開かれると、ドキュメント、フォーム、プレゼンテーション、スプレッドシートにアドオンが読み込まれます。 アドオンは [拡張機能] メニューに表示され、 シンプルなトリガー 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 の両方が実行されません。公開されたアドオンでメニュー項目を追加できない場合は、ブラウザ コンソールを確認してエラーが返されたかどうかを確認します。次に、スクリプトを調べて、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. コードを保存して、テスト デプロイを作成します。 テスト デプロイを作成するときは、[構成] フィールドが [現在のユーザーにインストール] になっていて、[構成] ボックスの下のテキストが [AuthMode.NONE でテスト] になっていることを確認します。
6. テスト デプロイを起動して、[拡張機能] メニューを開きます。
7. すべてのメニュー項目が表示されていれば、問題は解決しています。[ヘルプ] メニューのみが表示される場合は、手順 1 に戻ります。 サービス呼び出しを見落としている可能性があります。

関連トピック

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