このドキュメントでは、Gmail API 固有の認可と認証の情報について説明します。このドキュメントを読む前に、認証と認可の詳細で Google Workspace の一般的な認証と認可の情報をお読みください。
認可用に OAuth 2.0 を設定する
OAuth 同意画面を構成し、スコープを選択して、ユーザーとアプリ審査担当者に表示する情報を定義し、後で公開できるようにアプリを登録します。
Gmail API のスコープ
アプリに付与されるアクセスレベルを定義するには、認可スコープを特定して宣言する必要があります。認可スコープは OAuth 2.0 URI 文字列で、Google Workspace アプリ名、アプリがアクセスするデータの種類、アクセスレベルが含まれます。スコープは、ユーザーの 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.addons.current.message.metadata |
アドオンの実行時にメール メッセージのメタデータを表示する。 | デリケートなコンテンツ |
https://www.googleapis.com/auth/gmail.addons.current.message.readonly |
アドオンの実行中にメールを表示する。 | デリケートなコンテンツ |
https://www.googleapis.com/auth/gmail.labels |
ラベルの作成、読み取り、更新、削除のみ。 | センシティブではない |
https://www.googleapis.com/auth/gmail.send |
メッセージのみ送信。メールボックスの読み取り権限や変更権限がありません。 | デリケートなコンテンツ |
https://www.googleapis.com/auth/gmail.readonly |
すべてのリソースとそのメタデータを読み取る（書き込みオペレーションは不要）。 | 制限付き |
https://www.googleapis.com/auth/gmail.compose |
下書きを作成、読み取り、更新、削除する。メッセージと下書きを送信する。 | 制限付き |
https://www.googleapis.com/auth/gmail.insert |
メッセージの挿入とインポートのみ。 | 制限付き |
https://www.googleapis.com/auth/gmail.modify |
すべての読み取り/書き込みオペレーション。ただし、ゴミ箱をバイパスして、スレッドとメッセージを即時に完全に削除します。 | 制限付き |
https://www.googleapis.com/auth/gmail.metadata |
ラベル、履歴レコード、メール メッセージ ヘッダーなどのリソース メタデータは読み取りますが、メッセージ本文や添付ファイルは読み取りません。 | 制限付き |
https://www.googleapis.com/auth/gmail.settings.basic |
基本的なメール設定を管理します。 | 制限付き |
https://www.googleapis.com/auth/gmail.settings.sharing |
転送ルールやエイリアスなど、機密性の高いメールの設定を管理します。
注: このスコープで保護されているオペレーションは、管理上の使用のみに制限されます。これらは、ドメイン全体の委任があるサービス アカウントを使用している Google Workspace のお客様のみが使用できます。 |
制限付き |
https://mail.google.com/ |
アカウントのメールボックス（スレッドとメッセージの完全削除を含む）に対する完全アクセス権。このスコープは、アプリケーションでゴミ箱をバイパスして、スレッドとメッセージを即時かつ完全に削除する必要がある場合にのみリクエストする必要があります。その他のすべてのアクションは、制限の緩やかなスコープで実行できます。 | 制限付き |
上の表の「使用状況」列は、次の定義に従って、各スコープの機密性を示しています。
非機密 - 認可アクセスの最小領域を提供します。基本的なアプリ検証のみが必要です。この要件については、検証の準備手順をご覧ください。
機密 - Google ユーザーデータへのアクセスを許可します。機密スコープの確認プロセスが必要です。この要件について詳しくは、Google API サービス: ユーザーデータに関するポリシーをご覧ください。これらのスコープではセキュリティ評価は必要ありません。
制限付き - このスコープを使用すると、Google ユーザーデータに幅広くアクセスできるため、制限付きスコープの検証プロセスを行う必要があります。この要件については、Google API サービス: ユーザーデータに関するポリシーと特定の API スコープの追加要件をご覧ください。制限付きスコープのデータをサーバーに保存（または送信）する場合は、セキュリティ評価を行う必要があります。
ユーザーデータへのアクセスをリクエストする際の Gmail API の使用とアクセスに適用されるその他の情報については、Gmail API サービスのユーザーデータとデベロッパー ポリシーをご覧ください。
アプリが他の Google API にアクセスする必要がある場合は、それらのスコープも追加できます。Google API スコープの詳細については、OAuth 2.0 を使用した Google API へのアクセスをご覧ください。
OAuth の確認
機密性の高い特定の OAuth スコープを使用するには、アプリで Google の OAuth 検証プロセスが必要になる場合があります。アプリで検証を行うタイミングと必要な検証の種類を判断するには、OAuth 検証に関するよくある質問をご覧ください。Google API サービス: ユーザーデータに関するポリシーもご覧ください。