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

多くの Apps Script ベースのアプリでは、スクリプト プロジェクトが使用時に必要な権限をリクエストするため、承認は簡単です。

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

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

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

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

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

認可モデル

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

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

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

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

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

認可モード

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

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

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

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

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 で実行されます。

Editor アドオンの認証ライフサイクル

アドオンが現在のユーザー用にインストールされているか、現在のファイルで有効になっている場合、そのファイルが開かれると、ドキュメント、フォーム、プレゼンテーション、スプレッドシート用にアドオンが読み込まれます。アドオンが [拡張機能] メニューに表示され、シンプルなトリガー 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();
}

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. テスト デプロイを起動し、[拡張機能] メニューを開きます。

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

関連トピック

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