スコープ

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

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

マニフェストでスコープを宣言する URL 文字列を使用します。承認フローの中で、Apps Script は承認プロセス中に 人間が読める形式のスコープの説明です。例: Google Workspace アドオン 「現在のメッセージを読む」機能を使用してスコープはマニフェストに次のように記述されます。 https://www.googleapis.com/auth/gmail.addons.current.message.readonly。イベント中 承認フローで、このスコープを持つアドオンがユーザーに アドオン: アドオンの実行中にメール メッセージを表示する。

スコープの表示

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

  1. スクリプト プロジェクトを開きます。
  2. 左側の [概要] をクリックします。 。
  3. [Project OAuth Scopes]（プロジェクトの 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 クライアントの確認 いくつかのステップがあります詳細については、次のガイドをご覧ください。

制限付きスコープ

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

制限付きスコープの一覧を確認する 確認することをおすすめしますこれらのいずれかをアドオンで使用する場合は、準拠する必要があります。 新しい 特定の API スコープの追加要件 公開前です。

カレンダーのスコープ

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

範囲
イベント メタデータにアクセスする https://www.googleapis.com/auth/calendar.addons.execute

アドオンがカレンダーの予定のメタデータにアクセスする場合は必須。許可 イベント メタデータにアクセスする必要があります。

ユーザー生成イベントデータを読み取る https://www.googleapis.com/auth/calendar.addons.current.event.read

アドオンがユーザーが作成したイベントデータを読み取る必要がある場合は必須。 ユーザーが生成したイベントデータへのアクセスをアドオンに許可します。このデータは 使用可能な場合のみ、 <ph type="x-smartling-placeholder"></ph> 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 の高度なドライブ Service です。このため、 基本のドライブ サービス できます。ファイルの認証はファイル単位で付与され、 ユーザーがアプリの許可を取り消すと取り消されます。

詳しくは、 <ph type="x-smartling-placeholder"></ph> 選択したファイルに対するファイル アクセスをリクエストする例

Gmail アドオンのスコープ

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

Gmail を拡張する Google Workspace アドオンによく使用されるスコープは次のとおりです。 「必須」とラベル付けされたものは Google Workspace アドオン マニフェスト（アドオンが拡張する場合） Gmail。

また、非常に広範な https://mail.google.com スコープも必ず置き換えてください。 より限定的なスコープでアドオンとやり取りできる 不要です

範囲
新しい回答案を作成 https://www.googleapis.com/auth/gmail.addons.current.action.compose

アドオンで <ph type="x-smartling-placeholder"></ph> Compose アクション トリガーをご覧ください。 一時的に新しい下書きメールを作成し、 返信できます。<ph type="x-smartling-placeholder"></ph>をご覧ください。 メッセージの下書きを作成する をご覧ください。このスコープは、ファイアウォール ルールで <ph type="x-smartling-placeholder"></ph> 作成アクションをご覧ください。 アクセス トークンが必要です。

オープン メッセージのメタデータを読み取る https://www.googleapis.com/auth/gmail.addons.current.message.metadata

開いているメッセージのメタデータ（ できます。メッセージの内容を読み取れない アクセス トークンが必要です。

アドオンの作成アクションでメタデータを使用する場合は必須 提供します <ph type="x-smartling-placeholder"></ph> Compose アクションのスコープを指定します。Compose トリガーが メタデータへのアクセス権が必要です。実際には、このスコープを使用して 返信の受信者リスト（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 できます。プロジェクトで <ph type="x-smartling-placeholder"></ph> OAuth2 for Apps Script ライブラリを使用します。

ユーザーの言語 / 地域とタイムゾーンを読み取る https://www.googleapis.com/auth/script.locale

プロジェクトに現在のユーザーの言語 / 地域とタイムゾーンの学習を許可します。 <ph type="x-smartling-placeholder"></ph>をご覧ください。 詳しくは、ユーザーの言語 / 地域とタイムゾーンにアクセスするをご覧ください。

トリガーを作成する https://www.googleapis.com/auth/script.scriptapp

プロジェクトに作成を許可する <ph type="x-smartling-placeholder"></ph> トリガー。

サードパーティのリンクをプレビューする 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>をご覧ください。 @ メニューからサードパーティのリソースを作成する。