執事のセバスチャンが東京ドームのイベントをHipChatで教えてくれる

2014.06.11
Ruby/Rails
e-takano

こんにちは、 kano-e です。 HipChatで好きな emoticon は (ghost) です。

今日は HipChat API と HipChat API を使った 執事のセバスチャン についてお話したいと思います。

まずはセバスチャンの紹介

執事のセバスチャンは東京ドームのイベントを教えてくれる Ruby 製の HipChat Bot です。

弊社フィードフォースは後楽園駅徒歩五分、窓を開ければ東京ドームシティのジェットコースターの歓声と絶叫。便利で素敵なロケーションなのですが、東京ドームでコンサートや野球の試合がある日には混雑に巻き込まれる悲劇も多々。

「あれ、今日何かイベントやってるんだっけ？うわ、お店どこも混んでる……」※ 写真はイメージです

そんな悲劇を防ぐのが、セバスチャンの仕事のひとつです。

東京ドームや東京ドームシティホールでイベントのある日には、

東京ドームでは 18:00 より【巨人戦】巨人　ー　横浜DeNA 開催でございます。お帰りのお時間にはお気をつけ下さい。

このようにセバスチャンがお知らせをしてくれます。

ほかには、 MTG の時間になったら教えてくれたり、

まもなくのご予定がございます。18:00より新人さんふりかえり以上でございます。

業務終了の時間を教えてくれたり、

まもなく業務終了のお時間でございますが、お仕事のおかげんはいかがでしょうか。戸締まり用の鍵はご準備よろしゅうございますか？

朝には1日のスケジュールを読み上げてくれたりなど、

おはようございます。5月9日金曜日でございます。本日のご予定をお知らせいたします。 10:30 より CF朝会

HipChat 上でいくつかの仕事をこなしています。

ここからは HipChat API の話を

HipChat では API が公開されていて、その API を使うためのライブラリも各種言語で用意されています。

Ruby の場合hipchat-rb を使えば、

client = HipChat::Client.new(access_token, api_version: 'v1')
room = client[room_id_or_name]
room.send(
  'Sebastian',
  'おはようございます。5月9日金曜日でございます。',
  color: 'yellow',
  notify: true,
  message_format: 'text'
)

これだけのコードで、

おはようございます。5月9日金曜日でございます。

こんなふうに、投稿できてしまいます。

ご覧の通りとても簡単なのですが、実際に bot 運用しようとしたときには、 API のバージョンや指定するオプションのことなどで、少し迷ったり調べたりすることもありました。先程のコードに解説を入れる形で、その辺りのことをざっくりとまとめたいと思います。

HipChat::Client.new ... アクセストークンと API バージョンについて

client = HipChat::Client.new(access_token, api_version: 'v1')

HipChat::Client のインスタンスを作る時には、アクセストークンの指定が必要です。オプションの api_version は v1 か v2 を指定します。省略された場合のデフォルトは v1 です。

api_version にどちらのバージョンを指定するか、なのですが。バージョンによって使える API も変わり、また、必要なアクセストークンの取得方法も違ってきます。なので、まず使い道にあった api_version はどちらなのか、考える必要があります。

api_version v1

v1のAPI を使う場合は Group Admin にある API メニューから発行するトークンが必要です。 v1 の API は、主に room の操作(投稿を含む)か user の操作を行うものになります。

トークン発行時に type を Admin にすると room の新規作成など v1 の API がすべて使用可能です。 type を Notification にした場合、使える API はrooms/message とrooms/topic のみです。

この辺りはAuthenticationのページに説明がまとまっています。 room に投稿したい程度の用途であれば Notification で OK です。

api version v2

v2のAPI の場合、用途によって取得するトークンが変わります。

まず、ユーザ毎の設定メニュー(Account settings > API access)から、ユーザのトークンを取得できます。ユーザのトークンなので、例えば room へ投稿した場合も v1 の API と違って投稿者名の指定はできず、ユーザ自身の投稿となります。

また、 room の管理者であれば room のトークンを発行できます。このトークンでは、その room に対してのみ操作が可能です。 room への投稿は "Notification" という投稿者名になります。

ほかに Add-on を使う時に発行されるトークンもあるのですが、この記事では説明を省略いたします。

さて、どっち？

では、改めて v1 と v2 どちらかを選んでトークンを発行します。

セバスチャンは、そもそもroomに投稿するAPI しか使いません。あとは どうしても Sebastian という名前で投稿したい ので v1 を使うことにしました。

HipChat::Client#[] ... 部屋を指定

以下のコードで room を指定しています。

room = client[room_id_or_name]

HipChat の API で部屋を指定した場合、 room_name と room_id のどちらでも受け付けてくれるようになっているようです。

web から room の情報を見ると確認できる API ID という項目が room_id です。それを使って、 API で部屋を指定することができます。

room_name の指定でも構わないのですが、 room_name はユーザが自由に変更できてしまいますし、 room_name の変更があると当然古い room_name での指定は使えません。

ルーム名変更に怯えなくて済む room_id を使う方が安心です。

HipChat::Room#send ... 実際に部屋に投稿する

さて、実際に投稿を行っているのは以下の部分です。

room.send(
  'Sebastian',
  'おはようございます。5月9日金曜日でございます。',
  color: 'yellow',
  notify: true,
  message_format: 'text'
)

第一引数は投稿者名、これは hipchat-rb の仕様では必須なのですが、 v2 の API を使っている場合は、何を指定しても無視されます。

第二引数は、ご覧の通りの投稿内容。

それ以降はオプションです。オプションは必須ではないため、実は投稿したいだけであれば、

room.send('Sebastian', 'おはようございます。5月9日金曜日でございます。')

これだけでもできてしまいます。

それでは、

color: 'yellow',
  notify: true,
  message_format: 'text'

この部分は何を指定しているのか、ここからはその話になります。

:color ... テスト通ったお知らせは緑色にしたいな

APIからの投稿の時には color パラメータで投稿の背景色を選ぶことができます。選べる色は yellow , red , green , purple , gray の5色。

デフォルトは yellow です。 (ですので、実はセバスチャンの color: 'yellow' という指定は、なくても問題ないものだったりします)

ほかにも random という指定が使えるのですが、これの使い所がいまいちわかりません。

:notify ... API での発言て通知されないの？

参加している room 内で新しい投稿があると、アプリでは room 名の色が変わって新着の投稿が通知されるようになっています。 API 経由での投稿は、通常はそういった通知はされません。

ですが、あえて通知させたい、という時はあるかと思います。例えば、エラーがあったら気付けるように通知されて欲しい、というような場合です。

その場合は、 notify というパラメータで制御可能です。

v1 の API では boolean なパラメータは、値として 1 or 0 、v2 では true or false を指定することとなっています。 hipchat-rb ではバージョンの違いを考えずに boolean を指定できるようになっており、 true or false を渡せば、バージョンに応じたパラメータに変換してくれます。