スコープ

ユーザーは、データにアクセスしたり、ユーザーに代わって操作を行ったりするアドオンや他のアプリを承認する必要があります。ユーザーがアドオンを初めて実行すると、アドオンの 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 スコープの追加要件を遵守する必要があります。

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

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

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

エディタのスコープ

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

範囲
現在のドキュメント ファイルへのアクセス 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

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

アドオンが作成アクション トリガーでメタデータを使用する場合は必須です。 作成アクションの場合、作成トリガーでメタデータへのアクセスが必要な場合は、このスコープが必要です。実際には、このスコープにより、作成トリガーは返信メールの下書きの受信者リスト(宛先、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 サービスを使用した同様のアクションは許可されません。ファイルの承認はファイル単位で付与され、ユーザーがアプリの承認を取り消すと取り消されます。

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

アクセス トークン

ユーザーデータを保護するため、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 アプリケーション内にリソースへのリンクを挿入できるようにします。詳しくは、 @ メニューからサードパーティのリソースを作成するをご覧ください。