スコープ

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

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

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

Apps Script がさまざまなサービスで使用するスコープは、関連する API で使用されるスコープと重複しています。たとえば、Apps Script の カレンダー サービスでは、 Calendar API と同じスコープが多数使用されています。特定の Apps Script サービス メソッドに必要なスコープは、Apps Script リファレンス ドキュメントで確認できます。

表示スコープ

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

1. スクリプト プロジェクトを開きます。
2. 左側の [概要] info_outline をクリックします。
3. [プロジェクトの 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 クライアント検証を受ける必要があります。詳細については、次のガイドをご覧ください。

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

制限付きスコープ

特定のスコープは制限付きであり、ユーザーデータの保護に役立つ追加のルールが適用されます。 1 つ以上の制限付きスコープを使用する Gmail またはエディタ アドオンを公開する場合は、公開前にアドオンが指定されたすべての制限に準拠する必要があります。

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

Visual Studio Code 用の Google Workspace デベロッパー ツール拡張機能 には、スコープの説明や、機密性の高いスコープか制限付きスコープかなど、すべてのスコープに関する診断情報が表示されます。

Google Workspace アドオンのスコープを選択する

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

エディタのスコープ

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

Gmail

Google Workspace アドオン専用のスコープが用意されており、ユーザーの Gmail データを保護できます。これらのスコープは、必要な他のスコープとともに、アドオン マニフェストに明示的に追加します。

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

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

Google カレンダーのスコープ

次の表に、Google カレンダーを拡張する Google Workspace アドオンでよく使用されるスコープを示します。

Google Chat のスコープ

Google Chat API を呼び出すには、 Google Chat ユーザーまたは Google Chat アプリとして認証します。 認証の種類ごとに必要なスコープが異なり、すべての Chat API メソッドがアプリ認証をサポートしているわけではありません。

Chat のスコープと認証タイプについて詳しくは、 Chat API 認証と認可の概要をご覧ください。

次の表に、サポートされている認証タイプに基づく、よく使用される Chat API メソッドとスコープを示します。

Google ドライブのスコープ

次の表に、Google ドライブを拡張する Google Workspace アドオンでよく使用されるスコープを示します。

アクセス トークン

ユーザーデータを保護するため、Google Workspace アドオンで使用される Gmail スコープは、ユーザーデータへの一時的なアクセス権を付与します。一時的な アクセスを有効にするには、 GmailApp.setCurrentMessageAccessToken アクション イベント オブジェクトのアクセス トークンを使用して を呼び出します。

Gmail スコープを有効にするアクセス トークンは、ScriptApp.getOAuthToken から返されるアクセス トークンと同じではありません。アクション イベント オブジェクトで提供されるトークンを使用します。

次の例は、メッセージのメタデータへのアクセスを許可するようにアクセス トークンを設定する方法を示しています。この例に必要なスコープは 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 アドオンでよく使用されるスコープを示します。