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

スコープ

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

このフローの中で、プロンプトはアプリケーションが要求するものをユーザーに伝えます。できます。たとえば、アドオンがファイルに対する読み取り権限、ユーザーのメールメッセージを作成したり、カレンダーで予定を作成したりできます。アドオンのスクリプトプロジェクトでは、これらの個々の権限を OAuth スコープとして定義しています。

マニフェストでスコープを宣言する URL 文字列を使用します。承認フロー中に、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 へのあります。公開されているアドオンの場合、このスコープをよりよりアドオンのニーズに応える限定セットであり、これ以上のものはありません。

スクリプトプロジェクトで使用するスコープは、そのマニフェストファイルを実行します。マニフェストフィールド 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 クライアントの確認いくつかのステップがあります詳細については、次のガイドをご覧ください。

制限付きスコープ

特定のスコープは制限されており、それに役立つ追加のルールが適用されます。ユーザーデータを保護できます。公開しようとしている Gmail またはエディタのアドオンで制限付きスコープを使用する場合、アドオンは指定されたすべての制限することもできます。

公開を試みる前に、制限付きスコープの一覧を確認してください。アドオンでこれらの API を使用する場合は、公開前に特定の API スコープの追加要件に準拠する必要があります。

カレンダースコープ

以下は、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` アドオンでユーザー作成のイベントデータを書き込む必要がある場合に必須です。アドオンがユーザーが作成したイベントデータを編集できるようにします。このデータは使用可能な場合のみ、 <ph type="x-smartling-placeholder"></ph> `addOns.calendar.eventAccess` マニフェストフィールド `WRITE` または `READ_WRITE` に設定されている。

ドライブのスコープ

以下は、Google ドライブを拡張する Google Workspace アドオンでよく使用されるスコープです。

範囲

選択したアイテムのメタデータを読み取る

範囲
選択したアイテムのメタデータを読み取る	`https://www.googleapis.com/auth/drive.addons.metadata.readonly` アドオンでトリガーされるコンテキストに基づくインターフェースを実装する場合は必須ユーザーがドライブでアイテムを選択したときに表示されます。ユーザーが所有しているアイテムに関する制限付きのメタデータの読み取りをアドオンに許可します表示されます。メタデータはアイテムの ID に限定されます。タイトル、MIME タイプ、アイコンの URL、アドオンに権限があるかどうかアクセスできます。
ファイルごとのアクセス	`https://www.googleapis.com/auth/drive.file` アドオンが個々のドライブファイルにアクセスする必要がある場合に推奨されます。Apps Script の高度なドライブサービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的なドライブサービスを使用して同様のアクションを使用することはできません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。選択したファイルのファイルアクセスをリクエストする例をご覧ください。

https://www.googleapis.com/auth/drive.addons.metadata.readonly

アドオンでトリガーされるコンテキストに基づくインターフェースを実装する場合は必須ユーザーがドライブでアイテムを選択したときに表示されます。ユーザーが所有しているアイテムに関する制限付きのメタデータの読み取りをアドオンに許可します表示されます。メタデータはアイテムの ID に限定されます。タイトル、MIME タイプ、アイコンの URL、アドオンに権限があるかどうかアクセスできます。

ファイルごとのアクセス

https://www.googleapis.com/auth/drive.file

アドオンが個々のドライブファイルにアクセスする必要がある場合に推奨されます。Apps Script の高度なドライブサービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的なドライブサービスを使用して同様のアクションを使用することはできません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。

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

Gmail アドオンのスコープ

Google Cloud 用に作成されたスコープがいくつかあり、ユーザーの Gmail を保護する Google Workspace アドオン分析できます必要なことこれらのスコープを明示的に追加する他の依存関係とともに、アドオンマニフェストに必要ありません。

以下は、Gmail を拡張する Google Workspace アドオンでよく使用されるスコープです。アドオンが Gmail を拡張する場合は、[必須] とラベル付けされているスコープを Google Workspace アドオンマニフェストに追加する必要があります。

また、アドオンの非常に広範な https://mail.google.com スコープを、アドオンに必要な操作のみを許可する、より狭いスコープのセットに置き換えてください。

範囲
新しい下書きを作成する	`https://www.googleapis.com/auth/gmail.addons.current.action.compose` アドオンでコンポーズアクショントリガーを使用する場合は必須。一時的に新しい下書きメールを作成し、返信できます。<ph type="x-smartling-placeholder"></ph>をご覧ください。メッセージの下書きを作成するをご覧ください。このスコープは、ファイアウォールルールで <ph type="x-smartling-placeholder"></ph> 作成アクションをご覧ください。アクセストークンが必要です。
オープンメッセージのメタデータを読み取る	`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 Chat で使用される Google Workspace アドオンのみの付与ユーザーデータへのアクセスを一時的に許可できます。一時的なアクセスを有効にするには、関数 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 アドオンでよく使用されるスコープです。

範囲
現在のドキュメントファイルへのアクセス	`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 スライド API にアクセスする場合は必須。開いているプレゼンテーションのコンテンツに一時的にアクセスできるようにします。
ファイルごとのアクセス	`https://www.googleapis.com/auth/drive.file` アドオンが `onFileScopeGrantedTrigger` を使用する場合と、アドオンがドキュメント、スプレッドシート、スライド、ドライブ API にアクセスする場合に必要。以下を使用して、アプリで作成または開いたファイルへのアクセス権をファイルごとに付与します。 Apps Script の高度なドライブ Service です。ただし、基本的なドライブサービスを使用して同様のアクションを使用することはできません。ファイルの承認はファイルごとに付与され、ユーザーがアプリの承認を取り消すと取り消されます。

その他のスコープ

アドオンで他の Apps Script サービスを使用する場合は、追加のスコープが必要になることがあります。ほとんどの場合、これらのスコープを Apps Script が検出してマニフェストを自動的に更新できます。マニフェストのスコープリストを編集する際は、より適切な代替手段（より狭いスコープなど）に置き換える場合を除き、スコープを削除しないでください。

参考までに、この API でよく使用される 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` プロジェクトに現在のユーザーの言語 / 地域とタイムゾーンの学習を許可します。 <ph type="x-smartling-placeholder"></ph>をご覧ください。詳しくは、ユーザーの言語 / 地域とタイムゾーンにアクセスするをご覧ください。
トリガーを作成する	`https://www.googleapis.com/auth/script.scriptapp` プロジェクトがトリガーを作成できるようにします。
サードパーティのリンクをプレビューする	`https://www.googleapis.com/auth/workspace.linkpreview` アドオンがサードパーティサービスからのリンクをプレビューする場合は必須です。ユーザーが Google Workspace アプリを操作している間に、プロジェクトが Google Workspace アプリケーション内でリンクを表示できるようにします。詳細については、<ph type="x-smartling-placeholder"></ph>をご覧ください。スマートチップを使用してリンクをプレビューする
サードパーティのリソースを作成する	`https://www.googleapis.com/auth/workspace.linkcreate` アドオンがサードパーティのサービスでリソースを作成する場合には必須です。ユーザーがリソース作成フォームに送信した情報をプロジェクトが読み取り、Google Workspace アプリ内にリソースへのリンクを挿入できるようにします。詳細については、<ph type="x-smartling-placeholder"></ph>をご覧ください。 @ メニューからサードパーティのリソースを作成する。