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

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

このフローで、プロンプトは、アプリが実行する必要がある権限をユーザーに伝えます。たとえば、アドオンがユーザーのメール メッセージの読み取り権限や、カレンダーでの予定の作成権限を必要とする場合があります。アドオンのスクリプト プロジェクトで、これらの個々の権限を OAuth スコープとして定義します。

URL 文字列を使用して、マニフェストでスコープを宣言します。認証フローで、Apps Script によって人間が判読できるスコープの説明がユーザーに表示されます。たとえば、アドオンで「現在のドキュメントを読み取る」スコープを使用するとします。このスコープは、マニフェストに https://www.googleapis.com/auth/documents.currentonly として記述されます。このスコープのアドオンは、認証フロー中に、このアプリケーションがインストールされているドキュメントの表示と管理を行う権限をユーザーに依頼します。

注: Apps Script がさまざまなサービスに使用するスコープは、関連する API で使用されるスコープと重複しています。たとえば、Apps Script の Calendar Service は、Calendar API と同じスコープの多くを使用します。特定の Apps Script サービス メソッドに必要なスコープは、Apps Script のリファレンス ドキュメントで確認できます。

スコープの表示

スクリプト プロジェクトで現在必要なスコープは、次の手順で確認できます。

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.currentonly"
     ],
     ...
   }
   

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

OAuth の確認

機密性の高い OAuth スコープを使用するには、アドオンを公開する前に OAuth クライアントの確認を受ける必要があります。詳細については、次のガイドをご覧ください。

• Apps Script の OAuth クライアントの確認
• 未確認のアプリ
• OAuth の確認に関するよくある質問
• Google API サービス: ユーザーデータに関するポリシー

制限付きのスコープ

一部のスコープには制限があり、ユーザーデータの保護に役立つ追加ルールが適用されます。1 つ以上の制限付きスコープを使用する Gmail またはエディタのアドオンを公開する場合、アドオンを公開する前に、指定されたすべての制限事項に従う必要があります。

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

注: 可能であれば、制限付きスコープをアドオンで使用しないでください。使用しない場合、一般公開でアドオンの審査に合格するほうが簡単です。非公開のアドオンには、制限付きスコープを自由に使用できます。

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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