スコープ

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

このフローでは、アプリケーションが権限を必要とする理由がプロンプトに表示されます。たとえば、ユーザーのメールメッセージの読み取りや、カレンダーでの予定の作成をアドオンが権限を必要とする理由などです。アドオンのスクリプトプロジェクトでは、これらの個々の権限が OAuth スコープとして定義されます。

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

スコープを表示する

スクリプトプロジェクトで現在必要なスコープを確認するには、次の操作を行います。

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

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

明示的なスコープの設定

Apps Script は、必要な関数呼び出しのコードをスキャンして、スクリプトに必要なスコープを自動的に判断します。多くの場合はこれだけで十分ですが、公開されたアドオンでは、スコープをより直接的に制御する必要があります。

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

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

アドオンが現在使用しているスコープを表示します。スコープを狭めるなど、必要な変更を特定します。
アドオンのマニフェストファイルを開きます。
oauthScopes というラベルの付いた最上位フィールドを見つけます。存在しない場合は、追加できます。
oauthScopes フィールドは、文字列の配列を指定します。プロジェクトで使用するスコープを設定するには、この配列の内容を使用するスコープに置き換えます。たとえば、Gmail を拡張する Google Workspace アドオンの場合、次のようなものがあります。
```
{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  ...
}
```
マニフェストファイルの変更を保存します。

OAuth の確認

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

制限付きスコープ

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

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

Visual Studio Code 用の Google Workspace Developer Tools 拡張機能は、スコープの説明や、機密情報または制限付き情報であるかどうかなど、すべてのスコープの診断情報を提供します。

Google Workspace アドオンのスコープを選択する

以降のセクションでは、Google Workspace アドオンでよく使用されるスコープについて説明します。

エディタのスコープ

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

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

範囲
現在のドキュメントファイルへのアクセス	`https://www.googleapis.com/auth/documents.currentonly` アドオンが Apps Script Docs API にアクセスする場合は必須です。開いているドキュメントのコンテンツへの一時的なアクセス権を付与します。
現在のスプレッドシートファイルへのアクセス	`https://www.googleapis.com/auth/spreadsheets.currentonly` アドオンが Apps Script Sheets API にアクセスする場合は必須。開いているスプレッドシートのコンテンツへの一時的なアクセス権を付与します。
現在のスライドファイルへのアクセス	`https://www.googleapis.com/auth/presentations.currentonly` アドオンが Apps Script Slides API にアクセスする場合は必須。開いているプレゼンテーションのコンテンツへの一時的なアクセス権を付与します。
ファイルごとのアクセス	`https://www.googleapis.com/auth/drive.file` アドオンが `onFileScopeGrantedTrigger` を使用する場合、およびアドオンがドキュメント、スプレッドシート、スライド、ドライブの API にアクセスする場合に必要です。Apps Script の高度なドライブサービスを使用して、アプリで作成または開かれたファイルへのファイル単位のアクセス権を付与します。ただし、この場合、基本的な Drive サービスを使用した同様のアクションは許可されません。ファイルの承認はファイル単位で付与され、ユーザーがアプリの承認を取り消すと取り消されます。

Gmail

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

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:）にアクセスできます。
開いているメッセージの内容を読み取る	`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 カレンダーのスコープ

以下は、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 Chat のスコープ

Chat API を呼び出すには、Google Chat ユーザーまたは Chat 用アプリとして認証する必要があります。認証の種類ごとに必要なスコープが異なります。また、すべての Chat API メソッドがアプリ認証をサポートしているわけではありません。

Chat のスコープと認証タイプの詳細については、Chat API の認証と認可の概要をご覧ください。

次の表に、サポートされている認証タイプに基づいて、よく使用される Chat API メソッドとスコープを示します。

メソッド	アプリ認証がサポートされている	サポートされている認可スコープ
メッセージを送信する		ユーザー認証の場合: `chat.messages.create` `chat.messages` `chat.import` アプリ認証の場合: `chat.bot`
スペースを作成する		ユーザー認証の場合: `chat.spaces.create` `chat.spaces` `chat.import` アプリ認証と管理者による承認（デベロッパープレビューで利用可能）の場合: `chat.app.spaces.create` `chat.app.spaces`
スペースを作成してメンバーを追加する	—	ユーザー認証の場合: `chat.spaces.create` `chat.spaces`
スペースにユーザーを追加する		ユーザー認証の場合: `chat.memberships` `chat.memberships.app` `chat.import` アプリ認証と管理者による承認（デベロッパープレビューで利用可能）の場合: `chat.app.memberships`
Chat スペースのアクティビティまたはイベントを一覧表示する	—	ユーザー認証では、リクエストに含まれる各イベントタイプにスコープを使用する必要があります。メッセージに関するイベントの場合: `chat.messages` `chat.messages.readonly` リアクションに関するイベントの場合: `chat.messages.reactions` `chat.messages.reactions.readonly` `chat.messages` `chat.messages.readonly` メンバーシップに関するイベントの場合: `chat.memberships` `chat.memberships.readonly` スペースに関するイベントの場合: `chat.spaces` `chat.spaces.readonly`

Google ドライブのスコープ

以下は、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 の高度なドライブサービスを使用して、アプリで作成または開かれたファイルへのファイル単位のアクセス権を付与します。ただし、この場合、基本的な Drive サービスを使用した同様のアクションは許可されません。ファイルの承認はファイル単位で付与され、ユーザーがアプリの承認を取り消すと取り消されます。選択したファイルへのアクセスをリクエストする例をご覧ください。

https://www.googleapis.com/auth/drive.addons.metadata.readonly

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

ファイルごとのアクセス

https://www.googleapis.com/auth/drive.file

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

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

アクセストークン

ユーザーデータを保護するため、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 スコープ

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

次の表に、Google Workspace アドオンでよく使用されるスコープの一覧を示します。

範囲
ユーザーのメールアドレスを読み取る	`https://www.googleapis.com/auth/userinfo.email` プロジェクトが現在のユーザーのメールアドレスを読み取ることを許可します。
外部サービスへの呼び出しを許可する	`https://www.googleapis.com/auth/script.external_request` プロジェクトが `UrlFetch` リクエストを行うことを許可します。プロジェクトで Apps Script 向け OAuth2 ライブラリを使用する場合も、この設定が必要です。
ユーザーの言語 / 地域とタイムゾーンを読み取る	`https://www.googleapis.com/auth/script.locale` プロジェクトが現在のユーザーの言語 / 地域とタイムゾーンを学習できるようにします。詳しくは、ユーザーの言語 / 地域とタイムゾーンへのアクセスをご覧ください。
トリガーを作成する	`https://www.googleapis.com/auth/script.scriptapp` プロジェクトでトリガーを作成できるようにします。
サードパーティのリンクをプレビューする	`https://www.googleapis.com/auth/workspace.linkpreview` アドオンがサードパーティサービスのリンクをプレビューする場合は必須です。ユーザーが操作しているときに、プロジェクトが Google Workspace アプリケーション内のリンクを確認できるようにします。詳しくは、スマートチップを使用してリンクをプレビューするをご覧ください。
サードパーティリソースを作成する	`https://www.googleapis.com/auth/workspace.linkcreate` アドオンがサードパーティサービスでリソースを作成する場合は必須です。プロジェクトが、ユーザーがリソース作成フォームに送信した情報を読み取り、Google Workspace アプリケーション内にリソースへのリンクを挿入できるようにします。詳しくは、 @ メニューからサードパーティのリソースを作成するをご覧ください。