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

編集者アドオンの承認スコープ

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

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

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

注: currentonly スコープは、Apps Script サービス内でのみ使用できます。これには、Apps Script のAdvanced Services や Google Workspace API への直接呼び出しは含まれません。

スコープの表示

スクリプトプロジェクトで現在必要なスコープを確認する手順は次のとおりです。

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

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

明示的なスコープを設定する

Apps Script は、コードをスキャンして、必要な関数呼び出しを検出し、スクリプトに必要なスコープを自動的に決定します。ほとんどのスクリプトではこれで十分で、時間を節約できますが、公開済みのアドオンの場合は、スコープをより直接的に制御する必要があります。

たとえば、Apps Script では、デフォルトでアドオンスクリプトプロジェクトに非常に許容度の高いスコープ https://mail.google.com が付与されます。ユーザーがこのスコープを持つスクリプトプロジェクトを承認すると、そのプロジェクトにはユーザーの Gmail アカウントに対する完全アクセス権が付与されます。公開済みのアドオンの場合は、このスコープを、アドオンのニーズを満たす範囲に限定したセットに置き換える必要があります。

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

アドオンで現在使用されているスコープを表示する。より狭いスコープを使用するなど、どのような変更が必要かを判断します。
アドオンのマニフェストファイルを開きます。
oauthScopes というラベルの付いた最上位フィールドを見つけます。存在しない場合は、追加できます。
oauthScopes フィールドは、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を、使用するスコープに置き換えます。たとえば、スプレッドシートを拡張するエディタアドオンの場合、次のような内容になります。
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.container.ui",
    "https://www.googleapis.com/auth/spreadsheets"
  ],
  ...
}
```
マニフェストファイルの変更を保存します。

OAuth の確認

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

制限付きのスコープ

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

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

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

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

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

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

  /**
   * @OnlyCurrentDoc
   */

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