Gmailアドオンを作る (2)　メッセージ情報を表示しよう

アドオンでは、選択したメッセージを取得し利用できます。「カード」と呼ばれるUIを作成し、メッセージ情報を表示させてみましょう。

メール情報とoauthScopes

アドオンプログラムは、Gmailでメッセージを選択すると、onTriggerFunctionに設定した関数が実行され、アドオンのパネル部分に表示がされます。アドオンプログラムを自作するためには、「選択されたメッセージ」と「パネルに表示するUI」の使い方を理解する必要があります。

まず、メッセージ情報の取得から説明しましょう。メッセージ情報を利用するためには、マニフェストファイルのoauthScopesに、メッセージ利用のための項目を追記します。今回は、以下のように内容を修正しておきましょう。

リスト1

"oauthScopes": [
    "https://mail.google.com/",
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/gmail.addons.current.message.readonly"
],

今回は、アドオンのcurrent.message.metadataとcurrent.message.readonlyという項目を追記してあります。これにより、選択されたメッセージの情報へのアクセスが許可されるようになります。

カードセクションの組み込み

アドオンでは、CardBuilderというオブジェクトを使って「カード」と呼ばれるUIを作成します。これは前回、「ヘッダーだけのカード」というごくシンプルなものを作って表示しました。

カードには、ヘッダー以外のものも、もちろん追加できます。これらは「CardSection（カードセクション）」と呼ばれるものです。これは、以下のような形でCardオブジェクトを作成して組み込みます。

CardService.newCardBuilder()
     .setHeader( [CardHeader] )
     .addSection( [CardSection] )
     .addSection( [CardSection] )
    ……略……
     .build();

addSectionメソッドで、CardSectionオブジェクトを組み込みます。これは連続していくつでも呼び出し組み込んでいくことができます。

さまざまな「ウィジェット」の作成

では、カードセクションはどのようにして作成するのでしょうか。これは、以下のようにして作成するのです。

CardService.newCardSection().addWidget( ウィジェット )

addWidgetというメソッドを使い、「ウィジェット」というUI部品を組み込んでCardSectionを作成します。組み込むウィジェットは、UIの部品となるものです。このウィジェットはさまざまな種類が用意されています。今回は、テキストを表示するための2つのウィジェットを使ってみることにします。

TextParagraphウィジェット
CardService.newTextParagraph().setText( テキスト )

テキストを表示するだけのシンプルなウィジェットです。これは、newTextParagraphメソッドでオブジェクトを作成し、setTextメソッドで表示するテキストを設定して作ります。

KeyValueウィジェット
CardService.newKeyValue().setTopLabel( ラベル ).setContent( コンテンツ )

ラベルとテキストからなるウィジェットです。テキストの上や下に小さくラベルのテキストを表示します。上にラベルを設定する場合は「setTopLabel」メソッドを使い、テキストの下にラベルを設定する場合は「setBottomLabel」というメソッドを使います。

選択したメールの内容を表示するアドオン

では、これらの機能を利用して、選択したメールの内容を表示するアドオンを作成してみましょう。前回、作ったアドオンプロジェクトのスクリプトを以下のように修正して下さい。

リスト2

function buildAddOn(e) {
  var accessToken = e.messageMetadata.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

var id = e.messageMetadata.messageId;
  var msg = GmailApp.getMessageById(id);
  var subject = msg.getThread().getFirstMessageSubject();

// CardHeaderの作成
  var header = CardService.newCardHeader()
    .setTitle(subject);

// KeyValueウィジェットのCardSection
  var from = CardService.newCardSection()
    .addWidget(
      CardService.newKeyValue().setTopLabel("From:")
        .setContent(msg.getFrom())
    );

// TextParagraphウィジェットのCardSection
  var content = CardService.newCardSection()
    .addWidget(
      CardService.newTextParagraph()
        .setText(msg.getPlainBody())
    );

// CardBuilderでCardを作成
  var card = CardService.newCardBuilder()
    .setHeader(header)
    .addSection(from)
    .addSection(content)
    .build();

return [card];
}

スクリプトを保存し、アドオンを組み込んでいるGmailをリロードしてアドオンのアイコンをクリックしてみましょう。おそらくアドオンのパネルに「承認が必要です」といった表示が現れるはずです。これは、Gmailの機能にアクセスするための許可を得るためのものです。「アクセスを承認」リンクをクリックすると、Googleアカウントを選択するウインドウが現れるのでアカウントを選びます。これでGmailの機能にアクセスが許可されます。

• 「承認が必要です」と表示されたら、「アクセスを承認」リンクをクリックする

メールを選択すると、そのタイトル、送信者、内容がアドオンのパネルに表示されます。タイトルは、スレッドへの返信の場合は元のタイトル（最初に送られてきたメッセージのタイトル）が表示されるようになっています。

• メールを選択すると、タイトル、送信者、メールの内容が表示される

選択したメッセージの取得

では、修正したbuildAddOn関数を見てみましょう。ここでは、最初に「アクセストークン」というものを設定しています。

var accessToken = e.messageMetadata.accessToken;
GmailApp.setCurrentMessageAccessToken(accessToken);

関数に引数から、e.messageMetadata.accessTokenという値を取り出し、これをGmailAppのsetCurrentMessageAccessTokenメソッドで設定しています。アクセストークンというのは、スクリプトがGmailAppにアクセスする際に「このプログラムにアクセスさせてもいいのか？」をチェックするために用いられる値です。正しく値を設定することでメッセージへのアクセスが許可されます。

アクセストークンを設定したら、選択されたメッセージのIDを取得し、それをもとにGmailMessageオブジェクトを取得します。

var id = e.messageMetadata.messageId;
var msg = GmailApp.getMessageById(id);

選択されたメッセージのIDは、e.messageMetadata.messageIdという値として渡されます。これを使い、GmailApp.getMessageByIdでGmailMessageを取得すれば、選択されたメッセージの情報を得ることができます。

メールの情報取得

GmailMessageオブジェクトには、メールの情報を取得するメソッドがいろいろ揃っています。送信者はgetFromで得られますし、メールの内容は、プレーンなテキストとして取り出すならgetPlainBodyメソッドで得ることができます。

タイトルも、getSubjectというメソッドで得られますが、ここではメールのタイトルではなく、そのスレッドのタイトルを取り出して表示しています。

タイトルの取得
var subject = msg.getThread().getFirstMessageSubject();

getThreadでGmailThreadオブジェクトを取得し、getFirstMessageSubjectでその最初のメールのタイトルを取り出します。こうすれば、「Re: 〇〇」といったタイトルのメールも「〇〇」という元のタイトルを取り出して表示することができます。

これで、選択したメール情報を表示するアドオンができました。単純に「何かを表示する」だけなら、このように割と簡単に作ることができます。が、何かの処理を実行させるアドオンを作るには、もう少しアドオンプログラムについて掘り下げて理解する必要があるでしょう。これについては次回、説明することにしましょう。