編集者アドオンの承認

ほとんどの場合、使用する前にアドオンを承認する必要があります。多くの Apps Script プロジェクト(ウェブアプリなど)では、認可が単純です。スクリプト プロジェクトは、使用しようとすると不足している権限を要求します。承認されたら、スクリプト プロジェクトは自由に使用できます。スクリプト プロジェクトを使用するすべてのユーザーが個別に承認します。

エディタのアドオンの認証モデルは、より複雑です。これらのアドオンは、Google ドライブに存在するファイル(他のユーザーと共有可能なファイル)でも機能するため、異なる承認モードを考慮してエディタのアドオンを作成する必要があります。Google Workspace エディタ アプリの UI には、アドオン メニューも用意されています。このアドオンには、まだインストールしていないアドオンも表示されます。これにより、認証モデルがより複雑になります。

承認モデル

エディタのアドオンには 2 つのプロパティがあり、特に共有と使用が簡単です。

  • ストアからエディタのアドオンを取得すると、ユーザーが開くか作成するすべてのドキュメントのアドオン アドオンにそのアドオンが表示されます。これらのドキュメントの共同編集者は、実際にそれを使用するドキュメントを除き、アドオンが表示されません。
  • ドキュメントで編集者のアドオンを使用すると、共同編集者はアドオン メニューにもそのドキュメントが表示されます(ただし、そのアドオンがインストールされている場合を除く)。

この共有モデルは、ほとんどのユーザーにとって自然に感じられるものです。ただし、エディタのアドオンはドキュメントを開いたときに onOpen(e) 関数を自動的に実行してメニュー項目を追加するため、上記の動作により Apps Script の認証ルールが複雑になります。結局のところ、ユーザーはドキュメントを開くたびに個人データにアクセスするアドオンには納得できません。このガイドは、コードが実行できる機能とタイミングを理解するのに役立ちます。

インストール済みと有効

エディタのアドオンがメニューに表示される場合は、インストールと有効化という 2 つの状態(あるいはその両方)でエディタのアドオンが表示されます。編集者アドオンは、ストアでアドオンを選択し、Google データへのアクセスを許可すると、特定のユーザーインストールされます。一方、特定のドキュメントでは、アドオンを使用するときにアドオンが有効になっています。2 人のユーザーがドキュメントを共同編集していて、そのうちの 1 つがアドオンを使用している場合、そのアドオンは 1 人のユーザーにインストールされ、ドキュメントで有効になります。

次の表で 2 つの状態を要約します。スクリプトをアドオンとしてテストする場合は、これらの状態のいずれかまたは両方でテストを実行できます。

インストール済み 有効
対象 ユーザー ドキュメント
原因 ストアからアドオンを取得する そのドキュメントの使用中にストアからアドオンを取得する。または、
ドキュメントに以前にインストールしたアドオンを使用する。
メニューの表示先 そのユーザーのみが閲覧または作成するすべてのドキュメント そのドキュメントのすべての共同編集者
onOpen(e) の実行対象 AuthMode.NONE(有効にする場合でなければ、AuthMode.LIMITED) AuthMode.LIMITED

認証モード

エディタ アドオンは、ドキュメントが開いたときに自動的に onOpen(e) 関数を実行してメニュー項目を追加しますが、ユーザーを保護するために、Apps Script では onOpen(e) 関数で実行できる操作が制限されます。現在のドキュメントでアドオンが使用されていない場合、これらの制限はより重大になります。

具体的には、インストール状態と有効状態によって、onOpen(e) 関数が実行される認証モードが決まります。Apps Script では、Apps Script のイベント パラメータauthMode プロパティとして認証モードが渡されます。e.authMode の値は、Apps Script ScriptApp.AuthMode 列挙型の定数に対応します。

現在のドキュメントでエディタ アドオンが有効になっている場合、onOpen(e)AuthMode.LIMITED で実行されます。アドオンが有効でなく、インストールのみされている場合、onOpen(e)AuthMode.NONE で実行されます。

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

NONE LIMITED CUSTOM_FUNCTION FULL
曜日 onOpen(e)(ユーザーがアドオンをインストールしたものの、ドキュメントでアドオンを有効にしていない場合) onOpen(e)(それ以外は)
onEdit(e)(スプレッドシートのみ)
カスタム関数 それ以外のすべて:
インストール可能なトリガー
onInstall(e)
google.script.run
ユーザーデータへのアクセス 言語 / 地域のみ 言語 / 地域のみ 言語 / 地域のみ
ドキュメントへのアクセス権 × ○ - 読み取り専用
ユーザー インターフェースへのアクセス メニュー項目を追加する メニュー項目を追加する ×
Properties へのアクセス ×
JdbcUrlFetchへのアクセス権 × ×
その他のサービス Logger
Utilities
ユーザーデータにアクセスしないサービス ユーザーデータにアクセスしないサービス すべてのサービス

完全なライフサイクル

現在のユーザーにアドオンがインストールされているか、現在のドキュメントで有効になっている場合、アドオンはドキュメントに読み込まれ、アドオン メニューに表示され、シンプルなトリガー onInstall(e)onOpen(e)onEdit(e) のリッスンが開始されます。ユーザーがアドオンのメニュー項目のいずれかをクリックすると、実行されます。

インストール中

ストアからエディタのアドオンをインストールすると、onInstall(e) 関数が AuthMode.FULL で実行されます。これにより、アドオンで複雑な設定ルーティンを実行できますが、ドキュメントがすでに開いているため、onOpen(e) 関数が実行されていないため、メニュー項目の作成にも onInstall(e) を使用することが重要です。便宜上、このサンプルに示すように、onInstall(e) から onOpen(e) を呼び出すだけで済みます。

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

導入

ドキュメントを開くと、現在のユーザーがインストールしたエディタのアドオンがすべて読み込まれ、ドキュメントで共同編集者が有効になっていて、各 onOpen(e) 関数が呼び出されます。onOpen(e) が実行される承認モードは、アドオンがインストールされているか有効かによって異なります。

アドオンによって基本メニューのみが作成される場合、モードは関係ありません。このサンプルは、単純な onOpen(e) の様子を示しています。

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

ただし、保存されている Apps Script プロパティに基づいて動的メニュー項目を追加する、現在のドキュメントの内容を読み取る、または他の高度なタスクを実行する場合は、認可モードを検出して適切に処理する必要があります。このサンプルでは、onOpen(e) の高度な関数は次のようになります。認可モードに基づいて動作を変更します。

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();
}

実行中

ユーザーがアドオンのメニュー項目のいずれかをクリックすると、まず Apps Script がアドオンをユーザーがインストールしているかどうかを確認し、インストールされていない場合はインストールするように促します。ユーザーがアドオンを承認した場合、スクリプトは AuthMode.FULL のメニュー項目に対応する関数を実行します。また、アドオンは、まだ有効になっていない場合はドキュメントで有効になります。