スコープ

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

このフローでは、アプリがどのような操作を行う権限をユーザーに求めているのかがプロンプトで示されます。たとえば、アドオンがユーザーのメール メッセージを読み取る権限や、カレンダーに予定を作成する権限を求める場合があります。アドオンのスクリプト プロジェクトでは、これらの個々の権限を OAuth スコープとして定義します。

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

スコープの表示

スクリプト プロジェクトで現在必要なスコープを確認する手順は次のとおりです。

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

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

明示的なスコープを設定する

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

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

スクリプト プロジェクトで使用するスコープを明示的に設定するには、manifest ファイルを編集します。マニフェスト フィールド 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 クライアントの確認を受ける必要があります。詳細については、次のガイドをご覧ください。

• Apps Script の OAuth クライアントの確認
• 未確認のアプリ
• OAuth の確認に関するよくある質問
• Google API サービス: ユーザーデータ ポリシー

制限付きのスコープ

特定のスコープは制限付きで、ユーザーデータの保護に役立つ追加のルールが適用されます。制限付きスコープを 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 ドライブのスコープ

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