Gmail API のスコープの選択

このドキュメントでは、Gmail API 固有の認可と認証について説明します。このドキュメントを読む前に、認証と認可についてで Google Workspace の認証と認可に関する一般的な情報を確認してください。

認可用に OAuth 2.0 を構成する

OAuth 同意画面を構成し、スコープを選択して、ユーザーとアプリの審査担当者に表示される情報を定義し、後でアプリを公開できるようにアプリを登録します。

Gmail API のスコープ

アプリに付与するアクセスレベルを定義するには、承認スコープを特定して宣言する必要があります。認証スコープは、Google Workspace アプリ名、アクセスするデータの種類、アクセスレベルを含む OAuth 2.0 URI 文字列です。スコープとは、ユーザーの Google アカウント データを含む Google Workspace データを操作するためのアプリのリクエストです。

アプリがインストールされると、アプリで使用されるスコープの検証を求めるメッセージがユーザーに表示されます。一般に、できる限り狭い範囲のスコープを選択し、アプリで必要ないスコープはリクエストしないようにします。ユーザーは、明確に説明された限定的なスコープに対してアクセス権限を付与する傾向があります。

可能な限り、機密性の低いスコープを使用して、アプリに必要な特定の機能のみにアクセスを制限します。

機密性の高いスコープ以外

ほとんどのユースケースでは、次の Gmail API スコープが推奨されます。

スコープコード 説明
https://www.googleapis.com/auth/gmail.addons.current.action.compose アドオン操作時の下書きの管理とメールの送信。
https://www.googleapis.com/auth/gmail.addons.current.message.action アドオンの操作時にメール メッセージを表示します。
https://www.googleapis.com/auth/gmail.labels メールラベルを表示、編集する。

機密性の高いスコープ

スコープコード 説明
https://www.googleapis.com/auth/gmail.addons.current.message.metadata アドオンの実行時にメール メッセージのメタデータを表示します。
https://www.googleapis.com/auth/gmail.addons.current.message.readonly アドオンの実行時にメール メッセージを表示します。
https://www.googleapis.com/auth/gmail.send ユーザーに代わってメールを送信します。

制限付きスコープ

スコープコード 説明
https://mail.google.com/ Gmail からのすべてのメールの閲覧、作成、送信、完全削除を行えます。

注: ゴミ箱をバイパスしてスレッドとメッセージを直ちに完全に削除する必要がある場合にのみ、このスコープをリクエストします。他のすべての操作は、制限の緩いスコープを使用して実行できます。
https://www.googleapis.com/auth/gmail.readonly メール メッセージと設定を表示します。
https://www.googleapis.com/auth/gmail.compose 下書きの管理とメールの送信。
https://www.googleapis.com/auth/gmail.insert Gmail のメールボックスにメールを追加します。
https://www.googleapis.com/auth/gmail.modify Gmail アカウントのメールを閲覧、作成、送信します。このスコープでは、ゴミ箱をバイパスしてスレッドとメッセージを直ちに完全に削除することはできません。
https://www.googleapis.com/auth/gmail.metadata ラベルやヘッダーなど、メール メッセージのメタデータは表示されますが、メール本文は表示されません。
https://www.googleapis.com/auth/gmail.settings.basic Gmail のメール設定とフィルタを表示、編集、作成、変更します。
https://www.googleapis.com/auth/gmail.settings.sharing 機密メールの設定（例: メールを管理できるユーザー）を管理します。

注: このスコープで保護されているオペレーションは、管理用途に限定されます。これらは、ドメイン全体の委任を使用するサービス アカウントを使用している Google Workspace のお客様のみが利用できます。

上記の表のスコープは、次の定義に従って機密性を示しています。

ユーザーデータへのアクセスをリクエストする際の Gmail API の使用とアクセスを規定する追加情報については、Google Workspace API のユーザーデータとデベロッパーのポリシーをご覧ください。

アプリが他の Google API へのアクセスを必要とする場合は、それらのスコープも追加できます。Google API スコープの詳細については、OAuth 2.0 を使用して Google API にアクセスするをご覧ください。

特定の OAuth 2.0 スコープの詳細については、Google API の OAuth 2.0 スコープをご覧ください。

OAuth の確認

特定のプライベートな OAuth スコープを使用するには、アプリで Google の OAuth 確認プロセスを完了する必要がある場合があります。OAuth アプリの確認に関するよくある質問で、確認が必要かどうか、必要な確認の種類を確認できます。