スコープ

コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

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

このフローで、プロンプトは、アプリが実行しようとしている権限についてユーザーに伝えます。たとえば、アドオンがユーザーのメールを読み取る、またはカレンダーで予定を作成する権限を要求する場合があります。アドオンのスクリプト プロジェクトでは、個々の権限を OAuth スコープとして定義します。

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

スコープの表示

スクリプト プロジェクトで現在必要なスコープを確認するには、次の手順を行います。

  1. スクリプト プロジェクトを開きます。
  2. 左側の概要アイコン をクリックします。
  3. [Project OAuth Scopes] にスコープを表示します。

スクリプト プロジェクトの現在のスコープは、プロジェクト マニフェストの 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 スコープの追加要件を遵守する必要があります。

カレンダーのスコープ

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 Workspace アドオンのよく使用されるスコープを以下に示します。

範囲
選択したアイテムのメタデータの読み取り https://www.googleapis.com/auth/drive.addons.metadata.readonly

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

ファイルごとのアクセス https://www.googleapis.com/auth/drive.file

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

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

Gmail のアドオンのスコープ

ユーザーの Gmail データを保護するために、Google Workspace アドオン用に作成されたスコープがいくつかあります。アドオンコードに必要なその他のスコープとともに、これらのスコープをアドオン マニフェストに明示的に追加する必要があります。

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

オープン メッセージのメタデータ(件名や受信者など)への一時的なアクセス権を付与します。メッセージ コンテンツの読み取りは許可されず、アクセス トークンが必要です。

アドオンが 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 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 アドオンのよく使用されるスコープです。

範囲
現在のドキュメント ファイル アクセス 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 を使用し、ドキュメント、スプレッドシート、スライド、ドライブ REST API にアクセスする場合に必要です。Apps Script の高度なドライブ サービスを使用して、アプリによって作成または開かれたファイルへのファイルごとのアクセス権を付与します。ただし、基本的なドライブ サービスを使用した同様の操作は使用できません。ファイルの承認はファイルごとに許可され、ユーザーがアプリの承認を解除すると取り消されます。

その他の範囲

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

参考までに、Google Workspace アドオンとともに使用されることが多い Apps Script スコープのリストを以下に示します。

範囲
ユーザーのメールアドレスの読み取り https://www.googleapis.com/auth/userinfo.email

現在のユーザーのメールアドレスの読み取りをプロジェクトに許可します。

外部サービスへの呼び出しを許可する https://www.googleapis.com/auth/script.external_request

プロジェクトで UrlFetch リクエストを実行できるようにします。これは、プロジェクトで Apps Script 向け OAuth2 ライブラリを使用する場合にも必要です。

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

プロジェクトが現在のユーザーの言語 / 地域、タイムゾーンを学習できるようにします。 詳しくは、ユーザーの言語 / 地域、タイムゾーンにアクセスするをご覧ください。

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

プロジェクトがトリガーを作成できるようにします。