スコープ

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

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

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

Apps Script がさまざまなサービスで使用するスコープは、関連する API で使用されるスコープと重複しています。たとえば、Apps Script の Calendar サービスは、Calendar API と同じスコープを多数使用します。特定の Apps Script サービス メソッドに必要なスコープは、Apps Script のリファレンス ドキュメントで確認できます。

表示スコープ

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

  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 のいずれかを使用している場合は、公開前に特定の API スコープの追加要件に準拠させる必要があります。

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

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

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

エディタのスコープ

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

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

アドオンが Google 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 を使用する場合、およびアドオンがドキュメント、スプレッドシート、スライド、Drive API にアクセスする場合に必要。Apps Script の 高度な Google ドライブ サービスを使用して、アプリで作成または開かれたファイルへのファイル単位のアクセス権を付与します。これにより、基本的な 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

アドオンが 作成アクション トリガーを使用する場合は必須。アドオンが新しい下書きメッセージと返信を一時的に作成できるようにします。詳しくは、 下書きメッセージの作成をご覧ください。このスコープは、[メール作成に関するアクション]（/workspace/add-ons/gmail/extending-compose-ui）と組み合わせて使用されることがよくあります。アクセス トークンが必要です。
開いているメッセージのメタデータを読み取る https://www.googleapis.com/auth/gmail.addons.current.message.metadata

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

アドオンが作成アクション トリガーでメタデータを使用する場合は必須です。作成アクションの場合、作成トリガーがメタデータにアクセスする必要がある場合は、このスコープが必要です。実際には、このスコープにより、作成トリガーは返信メールの下書きの受信者リスト（宛先、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 のスコープ

Google Chat API を呼び出すには、Google Chat ユーザーまたは Google 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 サービスを使用する同様の操作は許可されなくなります。ファイルの承認はファイル単位で付与され、ユーザーがアプリの承認を取り消すと取り消されます。 選択したファイルへのアクセスをリクエストする例をご覧ください。

アクセス トークン

ユーザーデータを保護するため、Google Workspace アドオンで使用される Gmail スコープは、ユーザーデータへの一時的なアクセスを許可します。一時的なアクセスを有効にするには、アクション イベント オブジェクトのアクセス トークンを使用して GmailApp.setCurrentMessageAccessToken を呼び出します。

Gmail スコープを有効にするアクセス トークンは、ScriptApp.getOAuthToken から返されるアクセス トークンと同じではありません。アクション イベント オブジェクトで提供されるトークンを使用します。

次の例は、メッセージのメタデータへのアクセスを許可するアクセス トークンを設定する方法を示しています。この例に必要なスコープは 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 アプリケーション内にリソースへのリンクを挿入できるようにします。詳しくは、 @ メニューからサードパーティのリソースを作成するをご覧ください。