目次
Gmail APIの公開
6月の25、26日に開催された GoogleI/O において、Android の次期バージョンである Android L や Material Design、Android Wear 等が発表されていた裏でひっそりと「 Gmail API 」のβ版が公開されました。
これまで Gmail の内容を取得する場合には、IMAP を利用してメールクライアントとサーバーを標準的な方法で接続する、という標準的な方法もしくは RSS で未読の一覧を取得するという方法でしか実現できませんでした。しかし、今回公開された Gmail API では、HTTPS通信で JSON、XML、Google Protocol Buffers 形式でデータを取得できる他、Java や Python などの言語からも内部的に RESTAPI を利用して呼び出すことが可能です。これにより、IMAP に対応していないクラウド環境下でも各種メールの操作が可能になりました。
詳細は以下の公式ブログにて。
http://googleappsdeveloper.blogspot.ca/2014/06/introducing-new-gmail-api.html
Gmail API の概要
Gmail API では Oauth2.0 認証下でユーザーのメールBox への Restful なアクセスを提供し、メッセージやスレッド、ラベル、下書きに対する CRUD 操作に対応してます。例えば、メールの取得、作成、削除、検索やラベルの作成、修正、削除、といったことが可能です。他にも出来ることはたくさんあるので詳しくは公式ドキュメントを読んでみてください。
さらに、Google API では、Java、JavaScript、.NET、Python、Objective-C、PHP などの言語向けにクライアントライブラリが用意されています。今回はガジェットを作成する関係で Javascript のライブラリを用いたサンプルを実装しました。
また、すぐに Gmail API を試してみたい!という方はぜひAPI Explorerで試してみてください。
Google gadget(API)の概要
また、ガジェットとGadget API についても軽く説明しておきます。
ガジェットは HTML と Javascript で作成されたアプリケーションで、Webページや他のアプリケーションに埋め込むことが可能です。
次のガジェットは ”Hello,World!” と表示するガジェットです。
<?xml version="1.0" encoding="UTF-8" ?>
<Module>
<ModulePrefs title="hello world example" />
<Content type="html">
<![CDATA[
Hello, world!
]]>
</Content>
</Module>
ガジェットは XML で指定します。ModulePrefs タグにはタイトルや説明、作者といった情報が含まれます。コンテンツ タイプを html に指定した場合、<![CDATA[・・・・]]>の中に HTML と Javascript を記述していきます。
今回作るもの
「 Gmail Viewer 」とでも言うガジェットで、Gmail API を利用してメールの一覧表示が出来るものです。以下のサイトをご覧ください。
https://sites.google.com/a/yoshidumi.co.jp/gmailsample/
- Oauth 認証
- 受信Box内メールの閲覧
- メールの検索
- 未読/既読メールの判別
- 「さらに読む」機能 …
などが出来るようになってます。また、ガジェットなので簡単に GoogleSites 等に埋め込むことが可能です。
では早速 Gmail API ガジェットを作ってまいりましょう。
事前準備
developer console でプロジェクトを作成します。
Gmail API を有効にします。
ClientId を生成します。
実装
今回実装するのは、
Oauth 認証→取得したいメッセージのIdリストを取得→メッセージIdから各メッセージの詳細情報を得る。
です。
Oauth 認証
var clientId = "xxxxxxxxxxxxxxxxx"; //事前に生成しておいたClient ID
var scopes = "https://www.googleapis.com/auth/gmail.readonly";
function handleClientLoad() {
window.setTimeout(checkAuth,1);
}
function checkAuth() {
gapi.auth.authorize({client_id: clientId, scope: scopes, immediate: true}, handleAuthResult);
}
function handleAuthResult(authResult) {
var authorizeButton = document.getElementById('authorize-button');
if (authResult && !authResult.error) {
init();
} else {
$("#authorize-button").show();
authorizeButton.onclick = handleAuthClick;
}
}
function handleAuthClick(event) {
gapi.auth.authorize({client_id: clientId, scope: scopes, immediate: false}, handleAuthResult);
return false;
}
①Gmail API では以下の scope をサポートしています。
- https://mail.google.com/
フルアクセス可能なスコープ。スレッドやメッセージの削除を行いたい場合を除いては、他のスコープを利用すべき。 - https://www.googleapis.com/auth/gmail.modify
全ての read/write 処理を許可する。 - https://www.googleapis.com/auth/gmail.readonly
read 処理のみ許可する。(今回はこちらを指定しています) - https://www.googleapis.com/auth/gmail.compose
create,read,update,delete(下書きのみ)を許可。メッセージや下書きを送信することも可。
メッセージIDを取得
function init(){
makeApiCall({
‘includeSpamTrash’:false, //スパムやゴミ箱に入ったメッセージを含めるかどうか。Defaultではfalse
'userId': 'me', //取得対象の指定(この場合は自分)
'labelIds':['INBOX'], //ラベルを指定することで取得したいメッセージのレベルを指定できる
’maxResults':8 //最大取得件数,
'pageToken':xxxxxxxx //特定のページの結果を得たい場合に指定するToken
'q':xxxxxx //クエリを指定するとマッチしたメッセージが返ってくる。
});
}
function makeApiCall(option) {
gapi.client.load('gmail', 'v1', function() {
var request = gapi.client.gmail.users.messages.list(option);
request.execute(function(resp) {
-----------------省略-------------------
});
});
}
上記のリクエストパラメータのうち、必要なパラメータのみをセットします。このパラメータの組み合わせで、受信Box内のメールだけを取ってきたり、テキストボックスに入力された値をクエリにマッチしたメールを取得する、といったことが可能です。※詳細 Users.messages: list
リクエストが正しく実行されたら、以下のようなレスポンスが返ってきます。
{
"messages": [
users.messages Resource
],
"nextPageToken": string,
"resultSizeEstimate": unsigned integer
}
以下のような感じで messageId や nextPageToken(このTokenをパラメータに渡せば次の8件といったメールを取得できます)を取得できます。
request.execute(function(resp) {
var result = resp.messages;
nextPageToken = resp.nextPageToken;
-----------------省略--------------------------
for(var count in result){
var messageId = result[count].id;
}
-----------------省略--------------------------
});
メッセージの詳細情報を取得
次に、取得した messageId からメッセージの詳細情報を取得します。
Google のAPI は非同期に処理されます。そのため、Client Library では1度の通信で複数回 API を呼ぶための HttpBatch というものが用意されているので、これを使用します。
このHttpBatch はまず Batch を作り・・①、リクエストを Batch に追加し・・②、Batch を実行する・・③という使い方をします。
request.execute(function(resp) {
-----------------省略--------------------------
var result = resp.messages;
var requests = {};
var httpBatch = gapi.client.newHttpBatch(); //①
for(var count in result){
var messageId = result[count].id;
requests[messageId] = makeGetRequest(messageId);
httpBatch.add(requests[messageId],{'id':messageId}); //②
}
getUserMail(requests, httpBatch);
});
function makeGetRequest(messageId){
return gapi.client.request({
'path':'gmail/v1/users/me/messages/'+messageId,
'method':'GET',
'params':{'format': "full"}
});
}
function getUserMail(httpBatch) {
httpBatch.execute(function(resp){ //③
----------------省略------------------
});
}
リクエストが正しく実行されたら、以下のようなレスポンスが返ってきます。
{
"id": string,
"threadId": string,
"labelIds": [
string
],
"snippet": string,
"historyId": unsigned long,
"payload": {
"partId": string,
"mimeType": string,
"filename": string,
"headers": [
{
"name": string,
"value": string
}
],
"body": users.messages.attachments Resource,
"parts": [
(MessagePart)
]
},
"sizeEstimate": integer,
"raw": bytes
}
下記の headers には、件名や日付、送信者等の情報が入っています。また、labelIds には送信メールかどうかや受信Box内のメールどうか、未読メールかどうか、といったラベルのIdが入っています。このlabelIds を見れば、そのメールが未読かどうか分かります。
httpBatch.execute(function(resp){
for(var messageId in resp){
var result = resp[messageId].result;
var headers = result.payload.headers;
var labelIds = result.labelIds;
-----------------省略------------------
}
});
ガジェットの貼り付け
今回作成したガジェットは以下のように Google Sites に貼り付けてすぐにでも利用可能です。
まず、自分の Google sites に行き、右上の編集ボタンをクリックします。
そして、挿入したい場所にカーソルを合わせて、左上の挿入ボタンを押します。
その他のガジェット…を選びます。
最後に、フォームに「 https://sites.google.com/a/yoshidumi.co.jp/gmailsample/gmail.xml 」と入れ、追加ボタンを押すと、ガジェットが追加されるはずです。
まとめ
Gmail APIへのアクセスとメールの操作が簡単に出来ることを分かって頂けたでしょうか?もちろん今回紹介したのは Gmail API で出来ることのごく一部を使ってガジェットを作成したにすぎません。他にも例えば、Users.messages:insert は rfc822 形式のメールを、メールを送信することなく、直接メールBox に入れることができる機能ですが、これはいろいろごまかすのに使え(ゲフンゲフン。
ともかく、Gmail API では今回紹介した機能以外にもたくさんのことが出来ます( 参考 )。
Gmail API を使って自分専用のクライアントアプリを作成したり、自分のメールを分析してみたりするのもいいでしょう。ぜひ自分なりの使い方を見つけて、Gmail APIを試してみて下さい。