ユーザーは、データにアクセスしたり、ユーザーに代わって操作したりするアドオンやその他のアプリケーションを承認する必要があります。ユーザーがアドオンを初めて実行すると、アドオンの UI に承認フローを開始するための承認プロンプトが表示されます。
このフローでは、アプリケーションが権限を必要とする理由がプロンプトに表示されます。たとえば、アドオンがユーザーのメール メッセージの読み取りや、カレンダーでの予定の作成を権限を必要とする理由などです。アドオンのスクリプト プロジェクトでは、これらの個々の権限が OAuth スコープとして定義されます。
URL 文字列を使用して、マニフェストでスコープを宣言します。承認フローでは、Apps Script はスコープの説明を人間が読める形式でユーザーに提示します。たとえば、アドオンで「現在のドキュメントの読み取り」スコープを使用する場合、マニフェストには https://www.googleapis.com/auth/documents.currentonly と記述します。承認フローでは、このスコープを持つアドオンが、このアプリケーションがインストールされているドキュメントの閲覧と管理をアドオンに許可するようユーザーに求めます。
Apps Script がさまざまなサービスで使用するスコープは、関連する API で使用されるスコープと重複しています。たとえば、Apps Script の Calendar サービスは、Calendar API と同じスコープを多数使用します。特定の Apps Script サービス メソッドに必要なスコープは、Apps Script のリファレンス ドキュメントで確認できます。
表示スコープ
スクリプト プロジェクトで現在必要なスコープを確認するには、次の操作を行います。
- スクリプト プロジェクトを開きます。
- 左側の [概要] をクリックします。
- [プロジェクトの 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 のいずれかを使用している場合は、公開前に特定の API スコープの追加要件に準拠させる必要があります。
Visual Studio Code 用の Google Workspace デベロッパー ツール拡張機能は、スコープの説明や、機密情報または制限付き情報であるかどうかなど、すべてのスコープの診断情報を提供します。
エディタ アドオンのスコープ
エディタ用アドオンを構築する場合、必要なスコープは、アドオンコードが使用する Google Apps Script サービスとメソッドによって決まります。たとえば、Google スプレッドシート アドオンが、別のスプレッドシートから情報を読み取るために https://www.googleapis.com/auth/spreadsheets.readonly スコープを必要とする場合があります。
Apps Script は、スクリプト プロジェクトにコードを追加すると、使用するサービスに必要なスコープを自動的に判断します。エディタ用アドオンの場合、スコープを自分で決定して明示的に設定する代わりに、この自動スコープ収集に依存するだけで済むことがよくあります。
スコープを明示的に設定しておらず、エディタ アドオンが常に開いているエディタ ファイルの読み取りまたは書き込みのみを行う場合は、スクリプト プロジェクト ファイルのいずれかに次のコメントを追加します。
/**
* @OnlyCurrentDoc
*/
このコメントは、Apps Script に対して、設定するエディタ ファイルのスコープを currentonly に絞り込むよう指示します。たとえば、このコメントをスプレッドシート アドオン スクリプト プロジェクト ファイルに追加すると、アドオンは開いているスプレッドシートでの操作のみに権限が必要であり、ユーザーが Google ドライブに保存している他のスプレッドシートには権限が必要ないことを指定することになります。逆に、ユーザーが開いていないシートのデータを読み書きする必要があるスプレッドシート アドオンでは、このコメントを使用しないでください。