編集者アドオンの承認

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

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

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

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

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

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

認可モデル

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

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

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

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

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

インストール済み 有効
適用先 ユーザー ドキュメント、フォーム、プレゼンテーション、スプレッドシート
原因 ストアからアドオンを取得する ドキュメント、フォーム、プレゼンテーション、スプレッドシートの使用中にストアからアドオンを取得する、または
以前にインストールしたアドオンをドキュメント、フォーム、プレゼンテーション、スプレッドシートで使用する
メニューの公開先 そのユーザーのみ(ユーザーが開くまたは作成したすべてのドキュメント、フォーム、プレゼンテーション、スプレッドシート) ドキュメント、フォーム、プレゼンテーション、スプレッドシートのすべての共同編集者
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 モードで実行すると、アドオンはユーザーが承認したすべてのスコープを使用できるようになります。

Apps Script は、認証モードを Apps Script のイベント パラメータ eauthMode プロパティとして渡します。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();
}

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

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

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

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

コードで認証モードを正しく管理しないと、アドオン メニューが表示されないことがあります。例:

  • 現在の認証モードでサポートされていない Apps Script サービスの実行をアドオンが試みる。

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

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

  1. アドオンの Apps Script プロジェクトを開き、onOpen() 関数を見つけます。
  2. onOpen() 関数を検索して、Apps Script サービスまたはそれらに関連するオブジェクト(PropertiesServiceSpreadsheetAppGmailApp など)に関する記述を検索します。
  3. UI 要素の作成以外の目的でサービスを使用する場合は、サービスを削除するか、コメント ブロックで囲みます。.getUi().createMenu().addItem().addToUi() のメソッドのみを残します。また、関数の外部にあるサービスを見つけて削除します。
  4. 前の手順でコメント化または削除されたコード行を含む可能性のある関数(特に、生成された情報を使用する関数)を特定し、サービス呼び出しをそれを必要とする関数に移動します。前の手順で行った変更に合わせて、コードベースを再配置または書き換えます。
  5. コードを保存し、テストデプロイを作成します。

    テストデプロイを作成するときは、[Config] フィールドが「Installed for current user」であり、構成ボックスの下のテキストに「Test in AuthMode.None」と表示されていることを確認します。

  6. テストデプロイを開始し、[拡張機能] メニューを開きます。

  7. すべてのメニュー項目が表示される場合、問題は解決しています。[ヘルプ] メニューしか表示されない場合は、ステップ 1 に戻ります。 電話に出られなかった可能性があります。