このページは Cloud Translation API によって翻訳されました。

編集者アドオンの承認

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

エディタアドオンの承認モデルはより複雑です。これらのアドオンは、Google ドライブにあるファイル（他のユーザーと共有できるファイル）に対して機能するため、さまざまな承認モードを考慮してエディタ用アドオンを作成する必要があります。Google ドキュメントエディタの UI には [アドオン] メニューも用意されています。このメニューには、インストールしたアドオンが未承認の場合でも表示されます。これにより、認可モデルがさらに複雑になります。

承認モデル

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

ストアから入手したエディタアドオンは、開いたり作成したりしたすべてのドキュメント、フォーム、プレゼンテーション、スプレッドシートのアドオンメニューに表示されます。共同編集者が実際に使用するドキュメント、フォーム、プレゼンテーション、スプレッドシートを除き、アドオンは表示されません。
エディタ、アドオンをドキュメント、フォーム、プレゼンテーション、スプレッドシートで使用すると、共同編集者はアドオンメニューにもそのファイルを表示できます（ただし、そのアドオンもインストールされている場合を除く）。

この共有モデルは、ほとんどのユーザーにとって自然に感じられます。ただし、エディタ用アドオンは、Google ドキュメントエディタを開くと、自動的に onOpen(e) 関数を実行してメニュー項目を追加するため、上記の動作により、Apps Script の承認ルールが複雑になります。結局のところ、ドキュメント、フォーム、プレゼンテーション、スプレッドシートを開くたびに、個人データへのアドオンへのアクセスにユーザーは不快感を覚えます。このガイドは、コードができることと、そのタイミングを理解するのに役立ちます。

インストール済みと有効

エディタのアドオンは、メニューに「インストール済み」または「有効」の 2 つの状態のいずれか（または両方）があります。特定のユーザーに対してエディタのアドオンをインストールすると、そのユーザーはストアでアドオンを選択し、Google データへのアクセスを許可します。これに対して、特定のドキュメント、フォーム、プレゼンテーション、またはスプレッドシートでアドオンを使用するユーザーは、アドオンを有効にします。2 人のユーザーがコラボレーションし、そのうちの 1 人がアドオンを使用すると、1 人のユーザーにインストールされ、ファイルに対して有効になります。

次の表は、2 つの状態をまとめたものです。スクリプトをアドオンとしてテストする場合、テスト状態はどちらかまたは両方にするかを選択できます。

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

認証モード

エディタアドオンは、ドキュメント、フォーム、プレゼンテーション、スプレッドシートを開くと、自動的に onOpen(e) 関数を実行してメニュー項目を追加しますが、ユーザーのデータを保護するため、onOpen(e) 関数は実行できる動作を制限します。現在のドキュメント、フォーム、プレゼンテーション、スプレッドシートでアドオンが使用されていない場合、より厳しい制限が適用されます。

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

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

認証モードのコンセプトは、スクリプトエディタ、メニュー項目、Apps Script google.script.run 呼び出しなど、Apps Script のすべての実行に適用されます。ただし、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` へのアクセス	×	表示	○	表示
`Jdbc`、`UrlFetch` へのアクセス	×	×	表示	表示
その他のサービス	`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 のメニュー項目に対応する関数を実行します。ドキュメント、フォーム、プレゼンテーション、スプレッドシートでは、アドオンが有効になっていません（有効になっていない場合）。