このページは Cloud Translation API によって翻訳されました。

スコープ

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

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

スコープは、URL 文字列を使用してmanifestで宣言します。承認フロー中に、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 アカウントに対する完全アクセス権が付与されます。公開済みのアドオンの場合は、このスコープを、アドオンのニーズを満たす範囲に限定したセットに置き換える必要があります。

スクリプトプロジェクトで使用するスコープを明示的に設定するには、manifest ファイルを編集します。マニフェストフィールド 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 スコープの追加要件に準拠する必要があります。

Google Workspace アドオンのスコープを指定する

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

エディタのスコープ

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

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

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

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