ユーザーは、データにアクセスしたり、ユーザーに代わって操作を行ったりするアドオンや他のアプリを承認する必要があります。ユーザーがアドオンを初めて実行すると、アドオンの UI に承認フローを開始するための承認プロンプトが表示されます。
このフローでは、アプリケーションがどのような権限を必要としているかがユーザーに表示されます。たとえば、アドオンがユーザーのメール メッセージの読み取りやカレンダーでの予定の作成の権限を必要としている場合などです。アドオンのスクリプト プロジェクトでは、これらの個々の権限が OAuth スコープとして定義されています。
URL 文字列を使用して、マニフェストでスコープを宣言します。承認フローでは、Apps Script はユーザーにスコープの人間が読める説明を表示します。たとえば、アドオンで「現在のドキュメントの読み取り」スコープを使用する場合、マニフェストには https://www.googleapis.com/auth/documents.currentonly と記述します。このスコープを持つアドオンは、認証フローの中で、このアプリケーションがインストールされているドキュメントの表示と管理をアドオンに許可するようユーザーに求めます。
スコープを表示する
スクリプト プロジェクトで現在必要なスコープを確認するには、次の操作を行います。
- スクリプト プロジェクトを開きます。
- 左側の [概要] をクリックします。
- [プロジェクトの OAuth スコープ] でスコープを確認します。
スクリプト プロジェクトの現在のスコープは、プロジェクト マニフェストの oauthScopes フィールドで確認することもできますが、これらのスコープを明示的に設定した場合に限ります。
明示的なスコープの設定
Apps Script は、必要な関数呼び出しのコードをスキャンして、スクリプトに必要なスコープを自動的に判断します。ほとんどのスクリプトではこれで十分であり、時間を節約できますが、公開されたアドオンでは、スコープをより直接的に制御する必要があります。
たとえば、Apps Script では、アドオン スクリプト プロジェクトにデフォルトで非常に制限の緩いスコープ https://mail.google.com が付与されることがあります。ユーザーがこのスコープでスクリプト プロジェクトを承認すると、プロジェクトにはユーザーの Gmail アカウントに対する完全なアクセス権が付与されます。公開済みのアドオンでは、このスコープを、アドオンのニーズを満たす最小限のセットに置き換える必要があります。
スクリプト プロジェクトで使用するスコープは、マニフェスト ファイルを編集して明示的に設定できます。マニフェスト フィールド oauthScopes は、アドオンで使用されるすべてのスコープの配列です。プロジェクトのスコープを設定する手順は次のとおりです。
- アドオンが現在使用しているスコープを表示します。スコープを狭めるなど、必要な変更を特定します。
- アドオンのマニフェスト ファイルを開きます。
oauthScopesというラベルの付いた最上位のフィールドを見つけます。存在しない場合は、追加できます。oauthScopesフィールドは、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を、使用するスコープに置き換えます。たとえば、スプレッドシートを拡張するエディタ用アドオンの場合、次のようなものがあります。{ ... "oauthScopes": [ "https://www.googleapis.com/auth/script.container.ui", "https://www.googleapis.com/auth/spreadsheets" ], ... }マニフェスト ファイルの変更を保存します。
OAuth の確認
特定のプライベート データにかかわる OAuth スコープを使用する場合は、アドオンを公開する前に OAuth クライアントの確認を受ける必要があります。詳細については、次のガイドをご覧ください。
制限付きのスコープ
一部のスコープは制限されており、ユーザーデータの保護に役立つ追加のルールが適用されます。1 つ以上の制限付きスコープを使用する Gmail アドオンまたはエディタ用アドオンを公開する場合は、公開前に、指定されたすべての制限事項に準拠する必要があります。
公開を試みる前に、制限付きスコープの完全なリストを確認してください。アドオンがこれらのいずれかを使用している場合は、公開前に特定の API スコープの追加要件を遵守する必要があります。
Visual Studio Code 用の Google Workspace Developer Tools 拡張機能は、スコープの説明や機密情報または制限付き情報かどうかなど、すべてのスコープの診断情報を提供します。
エディタ アドオンのスコープ
エディタ用アドオンをビルドする場合、必要なスコープは、アドオンコードが使用する Apps Script サービスとメソッドによって決まります。たとえば、スプレッドシート アドオンが別の Google スプレッドシートから情報を読み取るには、https://www.googleapis.com/auth/spreadsheets.readonly スコープが必要になることがあります。
Apps Script は、スクリプト プロジェクトにコードを追加する際に、使用するサービスに必要なスコープを自動的に判断します。エディタ用アドオンの場合、スコープを自分で決定して明示的に設定するのではなく、この自動スコープ収集に依存するだけで済むことがよくあります。
スコープを明示的に設定しておらず、エディタ アドオンが開いているエディタ ファイルの読み取りまたは書き込みのみを行う場合は、次のコメントをスクリプト プロジェクト ファイルのいずれかに追加します。
/**
* @OnlyCurrentDoc
*/
このコメントは、Apps Script に対して、設定するエディタ ファイルのスコープを currentonly に絞り込むよう指示します。たとえば、このコメントを Google スプレッドシート アドオンのスクリプト プロジェクト ファイルに追加すると、アドオンは現在開いているシートでの操作に必要な権限のみを必要とし、ユーザーが Google ドライブに保存している他のシートでの操作に必要な権限は必要としないことを指定することになります。逆に、ユーザーが現在開いていないシートのデータを読み書きする必要がある場合は、このコメントを使用しないでください。