みなさんこんにちは。@FromAtomです。去年のアドベントカレンダーでは、 『【esa】社内ドキュメントツールのホッテントリを分かるようにしたら捗った話 』を書きました。今年もesaの話です。以前、中の人にインタビューしていただいた こともあるのですが、ピクシブではesaという情報共有サービスを利用しています。
社外秘の情報も書かれているためClosedなesaとして運用しており、もちろん外部の人はアクセスすることができません。そのため、Slackにesaの記事URLを貼っても展開機能が使えません。「それはそう」という感じなのですが、下の画像のPublicなesaのように、URLが展開されたほうが便利ですよね。
そこで、Slack AppのUnfurling links in messagesという機能を利用して、社内Slackに貼られたClosedな社内esaのURLでも展開できるようにしました。
実装方法
基本的にはUnfurling links in messages | Slack を読んで順番に実装していけば作ることができます。
Slack Appを作る
まずはSlack Appを作ります。
にアクセスしましょう。もしログインしていない場合は、URL展開機能を有効にしたいSlack Workspaceにログインして下さい。次に、Create New App
ボタンをクリックします。
そうすると、アプリの名前と実装するWorkspaceを入力する画面が出てきますので、好きな名前とWorkspaceを選んで下さい。入力が終わったら Create App
をクリックします。
次に、このような画面が出てくると思いますので、 Event Subscriptions
をクリックして下さい。
そうするとこういった画面になります。一番下の “App Unfurl Domains” で展開処理をしたいドメインを設定します。 Add Domain
ボタンから行えます。
設定が終わるとこんな感じです。この例では naisho.esa.io
というドメインを対象にしています。
なお、どのようなドメイン設定でどのようなURLがヒットするかについては、 https://api.slack.com/docs/message-link-unfurling に記載がありますのでそちらをご参照下さい。
ドメインの設定が終わったら、上にある “Subscribe to Workspace Events” を確認しましょう。ここに link_shared
のイベントが登録されていることを確認して下さい。
最後に一番下の Save Changes
ボタンをクリックして今の変更を保存をしましょう。忘れがちなので気をつけて下さい。
これで特定ドメイン(今回はnaisho.esa.io
)のURLが貼られたらイベントが発火するようになりました。つぎに、サーバからURL展開用の情報を受け取るための準備をしていきます。
この “OAuth & Permissions” をクリックします。
次に、 “Scopes” の “Select Permission Scopes” で links:read
と links:write
を追加します。おそらく links:read
はすでに追加済みだと思います。追加したあとは、 “Save Changes” ボタンを押すのをお忘れなく。
最後に “Install App to Workspace” をクリックします。
Workspaceへのインストールが無事に終わると、このように “OAuth Access Token” が表示されます。このTokenは後で使うので控えておいて下さい。
esaの準備
URL展開をしたいTeamにログインして、マイページから "Applications" を選びます。その後、”Personal access tokens”を新規生成します。権限はReadのみです。
ここで生成したTokenはもちろん後で使うので、忘れずに控えておいて下さい。
サーバサイドの準備
これでひとまずSlack App側の設定は一通り終わりなので、サーバサイドの準備にうつります。
Kujakuという拙作コードを用意したので、こちらを利用する前提でお話します。Deploy to Herokuボタンもつけてあるので便利です。デプロイ時には3つの環境変数を要求されます。
これらのTokenは今までの作業の中で手に入れているはずなので、そちらを入力してデプロイして下さい。
さて、デプロイが終わったら、ルートURLを控えておいて下さい。Herokuにデプロイした場合は、https://[your-heroku-app-name].herokuapp.com/
がそれにあたります。
つなぎこむ
いよいよ最後の作業です。まず最初に作ったSlack Appのページを開き、 “Event Subscription” のメニューをクリックします。次に、先程デプロイ後に控えておいたルートURLを “Request URL” にコピペします。
コピペをすると、サーバの検証が走りうまく行けばVerifiedと表示されます。もしエラーが出た場合は Learn more を見ながらサーバの設定やコードの修正をしましょう。
最後に、右上のスイッチをONにして、画面一番下の”Save Changes” ボタンを忘れずにクリックします。
これで、SlackにesaのURLが貼られたら展開されるようになったはずです。早速SlackにURLを投稿してみましょう!
無事に展開されれば成功です!もし展開される量が多いと感じた場合は、Kujaku 側をいじってみて下さい。
注意点
esaのAPIはユーザ毎に15分間に75リクエストまでの制限があります。他にesaのAPIを使うことが多かったり、非常に活発にesaのURLが貼られる場合はすぐに制限が来てしまって不便かもしれません。私が制作したKujakuでは一応Redisによるキャッシュ機能を持っていて、同一の記事ならesaのAPIを叩かずに処理ができますが、そんなにキャッシュヒット率が高いわけでもないので気休め程度です。
なお、esaだけでなく様々なURLに対して展開機能が作れますが、閲覧権限を限定したURLも全部展開してしまうと、権限がない人でも閲覧できるのと同じ状態になってしまうので、お気をつけ下さい。
さいごに
去年に引き続き、今年もesaに関してのアドベントカレンダーでした。esaはとても便利なツールなのでおすすめです。
ちなみに、esaだけでなく様々なURLの展開機能が作れるのですが、弊社ではScrapboxのURLを展開するSlack Appも動いています。Scrapboxもesa同様とても便利なツールなのでおすすめです。
ライセンス表記
本記事の上部で表示している画像です。