エディタ アドオンの認可スコープ

ユーザーは、データにアクセスしたり、ユーザーに代わって操作を行ったりするアドオンや他のアプリを承認する必要があります。ユーザーがアドオンを初めて実行すると、アドオンの UI に承認フローを開始するための承認プロンプトが表示されます。

このフローでは、アプリケーションが権限を必要とする理由がプロンプトに表示されます。たとえば、ユーザーのメール メッセージの読み取りや、カレンダーでの予定の作成をアドオンが権限を必要とする理由などです。アドオンのスクリプト プロジェクトでは、これらの個々の権限が OAuth スコープとして定義されます。

URL 文字列を使用して、マニフェストでスコープを宣言します。承認フローでは、Apps Script はスコープの説明を人間が読める形式でユーザーに提示します。たとえば、アドオンで「現在のドキュメントの読み取り」スコープを使用する場合、マニフェストには https://www.googleapis.com/auth/documents.currentonly と記述します。承認フローでは、このスコープを持つアドオンが、このアドオンに「このアプリケーションがインストールされているドキュメントの表示と管理」を許可するようユーザーに求めます。

スコープを表示する

スクリプト プロジェクトで現在必要なスコープを確認するには、次の操作を行います。

  1. スクリプト プロジェクトを開きます。
  2. 左側の [概要] をクリックします。
  3. [プロジェクトの OAuth スコープ] でスコープを確認します。

スクリプト プロジェクトの現在のスコープは、プロジェクト マニフェストの oauthScopes フィールドで確認することもできますが、これらのスコープを明示的に設定している場合に限ります。

明示的なスコープの設定

Apps Script は、必要な関数呼び出しのコードをスキャンして、スクリプトに必要なスコープを自動的に判断します。多くの場合はこれだけで十分ですが、公開されたアドオンでは、スコープをより直接的に制御する必要があります。

たとえば、Apps Script では、アドオン スクリプト プロジェクトに非常に緩いスコープ https://mail.google.com がデフォルトで付与されることがあります。ユーザーがこのスコープでスクリプト プロジェクトを承認すると、プロジェクトにユーザーの Gmail アカウントへの完全なアクセス権が付与されます。アドオンを公開する際は、このスコープを、アドオンのニーズを過不足なくカバーする、より限定的なセットに置き換える必要があります。

スクリプト プロジェクトで使用するスコープは、マニフェスト ファイルを編集して明示的に設定できます。マニフェスト フィールド oauthScopes は、アドオンで使用されるすべてのスコープの配列です。プロジェクトのスコープを設定する手順は次のとおりです。

  1. アドオンが現在使用しているスコープを表示します。スコープを狭めるなど、必要な変更を特定します。
  2. アドオンのマニフェスト ファイルを開きます。
  3. oauthScopes というラベルの付いた最上位フィールドを見つけます。存在しない場合は、追加できます。

  4. oauthScopes フィールドは、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を使用するスコープに置き換えます。たとえば、スプレッドシートを拡張するエディタ アドオンの場合、次のようになります。

    {
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}

  5. マニフェスト ファイルの変更を保存します。

OAuth の確認

特定のプライベート データにかかわる OAuth スコープを使用する場合は、アドオンを公開する前に OAuth クライアントの検証を受ける必要があります。詳細については、次のガイドをご覧ください。

制限付きスコープ

特定のスコープは制限付きに分類され、ユーザーデータの保護を目的とした追加のルールが適用されます。1 つ以上の制限付きスコープを使用する Gmail アドオンまたはエディタ用アドオンを公開する場合は、公開前にアドオンが指定されたすべての制限に準拠する必要があります。

公開前に、制限付きスコープの完全なリストを確認してください。アドオンでこれらの API のいずれかを使用している場合は、公開前に特定の API スコープの追加要件に準拠させる必要があります。

Visual Studio Code 用の Google Workspace Developer Tools 拡張機能は、スコープの説明や、機密情報または制限付き情報であるかどうかなど、すべてのスコープの診断情報を提供します。

エディタ アドオンのスコープ

エディタ用アドオンをビルドする場合、必要なスコープは、アドオンコードが使用する Apps Script サービスとメソッドによって決まります。たとえば、Sheets アドオンが別の Google スプレッドシートから情報を読み取るには、https://www.googleapis.com/auth/spreadsheets.readonly スコープが必要になることがあります。

Apps Script は、スクリプト プロジェクトにコードを追加する際に、使用するサービスに必要なスコープを自動的に判断します。エディタ用アドオンの場合、スコープを自分で決定して明示的に設定する代わりに、この自動スコープ収集に依存するだけで済むことがよくあります。

スコープを明示的に設定しておらず、エディタ アドオンが開いているエディタ ファイルの読み取りまたは書き込みのみを行う場合は、スクリプト プロジェクト ファイルのいずれかに次のコメントを追加します。

  /**
   * @OnlyCurrentDoc
   */

このコメントは、Apps Script に対して、設定するエディタ ファイルのスコープを currentonly に絞り込むよう指示します。たとえば、このコメントを Google スプレッドシート アドオンのスクリプト プロジェクト ファイルに追加すると、アドオンに必要な権限は現在開いているシートでの操作のみであり、ユーザーが Google ドライブに保存している他のシートでの操作は必要ないことを指定することになります。逆に、ユーザーが現在開いていないシートのデータを読み書きする必要がある場合は、このコメントを使用しないでください。