スコープ

ユーザーは、自分のデータにアクセスするアドオンやその他のアプリ、またはユーザーに代わって動作するアプリを承認する必要があります。ユーザーがアドオンを初めて実行すると、アドオンの 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 を使用する場合は、公開前に特定の API スコープの追加要件に準拠する必要があります。

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 の 高度なドライブ サービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的な ドライブ サービスを使用して同様のアクションを使用することはできません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。

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 の 高度なドライブ サービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的な ドライブ サービスを使用して同様のアクションを使用することはできません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。

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

アクセス トークン

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