サンプルアプリケーションのコード解説
それでは、サンプルアプリケーションのコードを解説しましょう。ポイントは次の2つです。
- Authorization Codeを取得するためのURLを表示する
- アクセストークンを取得してAPIを呼び出す
Authorization Codeを取得するためのURLを表示する
Authorization Codeを取得するためのURLには、パラメータとして、先に発行したClient IDのほかに、リソースに対して行う操作の種類を指定するScopeを指定する必要があります。
Gmail APIのScopeを調べるには、Gmail APIのリファレンス（https://developers.google.com/gmail/api/）を開き、左側のナビゲーションから「Guides」→「Authorized Requests」→「Auth Scopes」とドリルダウンします。すると、「Choose Auth Scopes」画面が開き、GmailのScopeが一覧できます。ScopeはURLの形になっています。今回は読み込みだけを行うので、https://www.googleapis.com/auth/gmail.readonlyを使います。
これでClient IDとScopeを取得できたので、Authorization Codeを取得するためのURLを組み立てられます。サンプルアプリケーションでは、これをbuildURLToGetAuthorizationCode()メソッドとして実装しています。
static String buildURLToGetAuthorizationCode(String clientId, String scopes)
throws IOException {
return new StringBuilder("https://accounts.google.com/o/oauth2/auth?")
.append("response_type=code")
.append("&client_id=").append(clientId)
.append("&redirect_uri=urn:ietf:wg:oauth:2.0:oob")
.append("&scope=").append(URLEncoder.encode(scopes, "utf-8"))
.toString();
}
https://accounts.google.com/o/oauth2/authにいくつかのパラメータを付加してURLを組み立てていますが、この組み立て方については「Using OAuth 2.0 to Access Google APIs」に詳しく書かれています。
ここでは簡単に、この実装で使用しているパラメータを説明しておきます。
response_type
Authorization Codeを取得する場合はcodeを設定します。
client_id
APIを利用するアプリケーションを識別するためのClient IDを設定します。
redirect_uri
Installed applicationの場合はurn:ietf:wg:oauth:2.0:oobを設定します。Web applicationの場合はコールバックURLを設定します。
scope
アクセスするリソースのScopeを設定します。複数のAPIを利用する場合はScopeも複数になりますが、その場合は複数のScopeを空白文字で連結します。
アクセストークンを取得してAPIを呼び出す
取得したAuthorization Codeを使ってアクセストークンを取得するには https://accounts.google.com/o/oauth2/tokenに対し、次のようにパラメータを組み立ててPOSTリクエストを行います（サンプルアプリケーションではexchangeToken()メソッドとして実装）。
byte[] parameters =
new StringBuilder()
.append("&code=").append(URLEncoder.encode(authorizationCode, "utf-8"))
.append("&client_id=").append(URLEncoder.encode(clientId, "utf-8"))
.append("&client_secret=").append(URLEncoder.encode(clientSecret, "utf-8"))
.append("&redirect_uri=urn:ietf:wg:oauth:2.0:oob")
.append("&grant_type=authorization_code").toString().getBytes("utf-8");
パラメータの意味は次のとおりです。
code
トークンと交換するためのAuthorization Code。
grant_type
authorization_codeを設定します。
このPostリクエストの結果、次のようなレスポンスがJSONで返されてきます。
{
"access_token": "ya29....",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "1/wsbgJ..."
}
ここから抜き出せるaccess_token（アクセストークン）とtoken_type（トークンタイプ）を使うことで、APIを利用することができます。サンプルコードのgmailApi()メソッドでは次のように実装し、Gmail APIを実行してラベルの一覧を取得（Users.labels: list）しています。
URL url = new URL("https://www.googleapis.com/gmail/v1/users/me/labels");
HttpURLConnection connection = (HttpURL Connection) url.openConnection();
connection.setRequestProperty("Authorization", tokenType + " " + accessToken);
InputStream inputStream = connection.getInputStream();
このように、Google APIと「OAuth2でアクセス許可を得て、JSON書式でhttpsを使って通信する」方法の場合、アクセストークンがわかれば、APIを実行するリクエストのAuthorizationヘッダにその値を指定するだけでAPIを利用できます。Google APIはライブラリを使うまでもなく簡単に実行できるのです。
アクセストークンを取得した時のレスポンスに含まれるJSONのexpires_inはaccess tokenの有効時間（秒）で、返されたaccess tokenはこの時間が過ぎると無効になってしまいます。
しかし、期限が切れた場合でも、refresh_tokenを使って新しいaccess tokenを取得できます。ですので、ユーザの許可を毎回求めたくない場合などは、アプリケーションにはリフレッシュトークンを保存することが多いです。
リフレッシュトークンを使ってアクセストークンを取得する方法は、「Using a refresh token」に説明があります。
まとめ
今回解説したことを最後に整理しておきましょう。
Google APIを利用する手順
- Develoepr Consoleでプロジェクトを作成する
- 利用するAPIをプロジェクトでONにする
-
アプリケーションの種類に応じた
Client IDを作成する - 利用するAPIのスコープを調べる
- ユーザにリソースへのアクセス許可をしてもらい、アクセストークンを取得する
-
アクセストークンを
Authorizationヘッダに設定する
基本を学べば、どのAPIも大差ない
Googleは様々なAPIを提供していますが、今回説明した方法で全てのAPIを使うことができます。API Explorerなどの便利なツールの存在や、似たようなインターフェース、認可の方法などの知識は、1つのAPIで経験すると、別のAPIでも同じように活用できます。
