スコープ

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

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

マニフェストでスコープを宣言するには、URL 文字列を使用します。承認フローで、Apps Script は人間が読める形式のスコープの説明をユーザーに表示します。たとえば、Google Workspace アドオンは、「現在のメッセージを読み取る」スコープを使用することがあります。これは、マニフェストに https://www.googleapis.com/auth/gmail.addons.current.message.readonly として記述されています。このスコープを持つアドオンは、承認フロー中に、アドオンの実行時にメール メッセージを表示することをアドオンに許可するようユーザーに求めます。

スコープの表示

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

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

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

明示的なスコープの設定

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

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

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

  1. アドオンで現在使用しているスコープを表示する。範囲を狭めるなど、必要な変更を特定します。
  2. アドオンのマニフェスト ファイルを開きます
  3. oauthScopes というラベルの付いた最上位のフィールドを見つけます。存在しない場合は追加できます。
  4. oauthScopes フィールドには、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を、使用するスコープに置き換えます。たとえば、Gmail を拡張する Google Workspace アドオンの場合、次のようになります。

    {
      ...
      "oauthScopes": [
        "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
        "https://www.googleapis.com/auth/userinfo.email"
      ],
      ...
    }
    
  5. マニフェスト ファイルの変更を保存します。

OAuth の確認

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

制限付きスコープ

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

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

カレンダーのスコープ

以下は、Google カレンダーの機能を拡張する Google Workspace アドオンでよく使用されるスコープです。

範囲
イベントのメタデータにアクセスする https://www.googleapis.com/auth/calendar.addons.execute

アドオンがカレンダーの予定のメタデータにアクセスする場合は必須。アドオンがイベント メタデータにアクセスできるようにします。

ユーザー生成イベントデータを読み取る https://www.googleapis.com/auth/calendar.addons.current.event.read

アドオンがユーザー生成イベントデータを読み取る必要がある場合は必須。 アドオンにユーザーが作成したイベントデータへのアクセスを許可します。このデータは、 addOns.calendar.eventAccess マニフェスト フィールドREAD または READ_WRITE に設定されている場合にのみ利用できます。

ユーザー生成イベントデータを書き込む https://www.googleapis.com/auth/calendar.addons.current.event.write

アドオンがユーザー生成イベントデータを書き込む必要がある場合は必須。 アドオンでユーザーが作成したイベントデータの編集を許可します。このデータは、 addOns.calendar.eventAccess マニフェスト フィールドWRITE または READ_WRITE に設定されている場合にのみ利用できます。

ドライブのスコープ

以下は、Google ドライブを拡張する Google Workspace アドオンでよく使用されるスコープです。

範囲
選択したアイテムのメタデータを読み取る https://www.googleapis.com/auth/drive.addons.metadata.readonly

ユーザーがドライブでアイテムを選択したときにトリガーされるコンテキスト インターフェースをアドオンが実装する場合は必須。 ユーザーが Google ドライブで選択したアイテムに関する制限付きメタデータの読み取りを許可します。メタデータは、アイテムの ID、タイトル、MIME タイプ、アイコン URL、アドオンにアイテムへのアクセス権限があるかどうかに限定されます。

ファイルごとのアクセス https://www.googleapis.com/auth/drive.file

アドオンが個々のドライブ ファイルにアクセスする必要がある場合におすすめします。 Apps Script の高度なドライブ サービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的なドライブ サービスを使用した同様のアクションは使用できません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの許可を取り消すと取り消されます。

選択したファイルに対するファイル アクセスをリクエストする例をご覧ください。

Gmail アドオンのスコープ

ユーザーの Gmail データを保護するため、Google Workspace アドオン専用に作成されたスコープがいくつかあります。アドオン コードに必要な他のスコープとともに、アドオン マニフェストにこれらのスコープを明示的に追加する必要があります。

以下は、Gmail を拡張する Google Workspace アドオンでよく使用されるスコープです。アドオンが Gmail を拡張する場合は、Google Workspace アドオン マニフェストに「必須」というラベルが付いたスコープを追加する必要があります。

また、アドオンの非常に広範な https://mail.google.com スコープを、アドオンが必要とする操作のみを可能にする、より狭い一連のスコープに置き換えてください。

範囲
新しい回答案を作成する https://www.googleapis.com/auth/gmail.addons.current.action.compose

アドオンが 作成アクション トリガーを使用する場合は必須。アドオンが一時的に新しいメッセージと返信の下書きを作成できるようにします。詳しくは、 メッセージの下書きを作成するをご覧ください。このスコープは 作成アクションでもよく使用されます。アクセス トークンが必要です。

開いているメッセージのメタデータを読み取る https://www.googleapis.com/auth/gmail.addons.current.message.metadata

開いているメッセージのメタデータ(件名や受信者など)への一時的なアクセス権を付与します。メッセージ コンテンツの読み取りが許可されておらず、アクセス トークンが必要です。

アドオンが作成アクション トリガーでメタデータを使用する場合は必須。 作成アクションで、作成トリガーがメタデータにアクセスする必要がある場合、このスコープが必要です。実際には、このスコープを使用すると、返信メールの下書きの受信者リスト(to:、cc:、bcc:)にアクセスする Compose トリガーが有効になります。

開いているメールの内容を読む https://www.googleapis.com/auth/gmail.addons.current.message.action

アドオン メニュー アイテムが選択された場合など、ユーザー操作時に開いているメッセージのコンテンツへのアクセスを許可します。アクセス トークンが必要です。

開いているスレッドの内容を読む https://www.googleapis.com/auth/gmail.addons.current.message.readonly

開いているメッセージのメタデータとコンテンツへの一時的なアクセス権を付与します。また、開いているスレッド内の他のメッセージのコンテンツへのアクセス権を付与します。アクセス トークンが必要です。

メッセージのコンテンツとメタデータを読み取る https://www.googleapis.com/auth/gmail.readonly

メールのメタデータと内容(開いているメールを含む)を読み取ります。検索クエリを実行するときやメールスレッド全体を読み取るときなど、他のメッセージに関する情報を読み取る必要がある場合は必須です。

アクセス トークン

ユーザーデータを保護するため、Google Workspace アドオンで使用される Gmail スコープでは、ユーザーデータへの一時的なアクセス権のみが付与されます。一時的なアクセスを有効にするには、アクセス トークンを引数として使用して、関数 GmailApp.setCurrentMessageAccessToken(accessToken) を呼び出す必要があります。アクセス トークンは、アクション イベント オブジェクトから取得する必要があります。

メッセージのメタデータへのアクセスを許可するアクセス トークンの設定例を次に示します。この例で必要なスコープは https://www.googleapis.com/auth/gmail.addons.current.message.metadata のみです。

function readSender(e) {
  var accessToken = e.gmail.accessToken;
  var messageId = e.gmail.messageId;

  // The following function enables short-lived access to the current
  // message in Gmail. Access to other Gmail messages or data isn't
  // permitted.
  GmailApp.setCurrentMessageAccessToken(accessToken);
  var mailMessage = GmailApp.getMessageById(messageId);
  return mailMessage.getFrom();
}

エディタのスコープ

ドキュメント、スプレッドシート、スライドを拡張する Google Workspace アドオンでよく使用されるスコープを以下に示します。

範囲
現在のドキュメント ファイル アクセス https://www.googleapis.com/auth/documents.currentonly

アドオンが Apps Script ドキュメント API にアクセスする場合は必須。開いているドキュメントのコンテンツへの一時的なアクセス権を付与します。

現在のスプレッドシート ファイル アクセス https://www.googleapis.com/auth/spreadsheets.currentonly

アドオンが Apps Script Sheets API にアクセスする場合は必須。開いているスプレッドシートのコンテンツへの一時的なアクセス権を付与します。

現在のスライドのファイルへのアクセス権 https://www.googleapis.com/auth/presentations.currentonly

アドオンが Apps Script Sheets API にアクセスする場合は必須。 開いているプレゼンテーションのコンテンツへの一時的なアクセス権を付与します。

ファイルごとのアクセス https://www.googleapis.com/auth/drive.file

アドオンで onFileScopeGrantedTrigger を使用する場合と、Google ドキュメント、スプレッドシート、スライド、ドライブの API にアクセスする場合に必要です。 Apps Script の高度なドライブ サービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的なドライブ サービスを使用した同様のアクションは使用できません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。

その他のスコープ

アドオンで他の Apps Script サービスを使用している場合は、追加のスコープが必要になる場合があります。ほとんどの場合、Apps Script でこれらのスコープを検出し、マニフェストを自動的に更新できます。マニフェストのスコープリストを編集するときは、より適切な代替(範囲の狭いスコープなど)に置き換える場合を除き、スコープを削除しないでください。

参考までに、Google Workspace アドオンと組み合わせて使用されることが多い Apps Script のスコープのリストを以下に示します。

範囲
ユーザーのメールアドレスを読み取る https://www.googleapis.com/auth/userinfo.email

現在のユーザーのメールアドレスの読み取りをプロジェクトに許可します。

外部サービスの呼び出しを許可する https://www.googleapis.com/auth/script.external_request

プロジェクトに UrlFetch リクエストを許可します。これは、プロジェクトで OAuth2 for Apps Script ライブラリを使用している場合にも必要になります。

ユーザーの言語 / 地域とタイムゾーンを読み取る https://www.googleapis.com/auth/script.locale

現在のユーザーの言語 / 地域とタイムゾーンの学習をプロジェクトに許可します。 詳しくは、 ユーザーの言語 / 地域とタイムゾーンへのアクセスをご覧ください。

トリガーを作成する https://www.googleapis.com/auth/script.scriptapp

プロジェクトによる トリガーの作成を許可します。

サードパーティのリンクをプレビューする https://www.googleapis.com/auth/workspace.linkpreview

アドオンがサードパーティ サービスからのリンクをプレビューする場合は必須。 ユーザーが Google Workspace を操作している間に、Google Workspace アプリ内でリンクを参照できるようにします。 詳しくは、 スマートチップを使用してリンクをプレビューするをご覧ください。

サードパーティ リソースを作成する https://www.googleapis.com/auth/workspace.linkcreate

アドオンがサードパーティ サービスでリソースを作成する場合は必須です。 ユーザーがリソース作成フォームに送信した情報をプロジェクトが読み取り、Google Workspace アプリケーション内にリソースへのリンクを挿入できるようにします。詳細については、 @ メニューからサードパーティのリソースを作成するをご覧ください。