ホーム ブログ Slack を統合する...

SlackとSwaggerを統合しましょう！

ロリンダ・ブランドン
  2015年8月20日

著者: Will Witman および Marsh Gardiner

Slack は、今日の最も注目されているスタートアップの1つであり、チームコミュニケーションのためのメッセージングアプリです。Slack が非常に人気がある理由の1つは、GitHub、Google Drive、Heroku、Jira など、多くの外部サービスがすぐに使える統合機能として提供されていることです。しかし、特に素晴らしい機能は、独自のカスタム機能を簡単に作成できることです。

今日は、swagger-node を使用して独自の Slack 統合を作成する手順を説明します。swagger-node を使用すると、Swagger と Node.js を使用して API プロジェクトをローカルで簡単に構築、検証、テストできます。その後、Node.js をサポートする任意のクラウドプラットフォームにプロジェクトをデプロイできます。このケースでは、株価を取得する API を作成し、Slack の「Incoming WebHook」統合を使用して、その株価を Slack チームの会話に直接投稿します。

alt text

この API のバックエンドリソースは /ticker であり、cURL で呼び出すことができます。

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" https://:10010/ticker -d "text=AAPL

...すると、このように Slack できれいにフォーマットされた応答が返されます。

alt text

API はローカルで実行およびテストしますが、Apigee、AWS、Heroku など、Node.js をサポートする任意のクラウドプラットフォームにデプロイできます。

開始する前に

以下の手順を試す場合は、Slack チームのメンバーであるか、新しいチームを作成する必要があります。どちらの場合も、統合を作成する権限が必要です。

GitHub からサンプル swagger-node-slack アプリを入手する

非常に簡単にするために、動作するプロジェクトをダウンロードできます。

  1. GitHub から swagger-node-slack プロジェクトをダウンロードまたはクローンします。

  2. ルートプロジェクトディレクトリ swagger-node-slack に移動します。

  3. Node.js の依存関係を取得するためにこのコマンドを実行します: npm install

ティッカーボット統合の構築

/ticker API を Slack と統合する手順を説明します。驚くほど簡単です。

まず、内部を簡単に見てみましょう

swagger-node-slack プロジェクトを簡単に見てみましょう。

(swagger-node プロジェクト構造に慣れていない場合は、ドキュメントを確認し、必要に応じてクイックスタートチュートリアルを試すことができます。)

swagger-node-slack API の仕組みを理解するための鍵は、次の2つのファイルを見ることです。

  • ./swagger-node-slack/api/swagger/swagger.yaml -- これは API の Swagger 定義です。サービスへのパス、操作、パラメータを定義していることに注意してください。組み込みの Swagger エディタを使用して、swagger project edit で変更を加えることができます。

これらのエンティティは、次に説明する対応するコントローラーファイルに直接関連付けられています。

    ...
    paths: 
        /ticker:
        # binds app logic to a route
        x-swagger-router-controller: ticker
        post:
          description: look up a stock price
          # used as the method name of the controller
          operationId: ticker
          consumes:
            + application/x-www-form-urlencoded
          parameters:
            + $ref: "#/parameters/text"
            + $ref: "#/parameters/user_name"
            + $ref: "#/parameters/icon_url"
            + $ref: "#/parameters/icon_emoji"
            + $ref: "#/parameters/channel"
          responses:
            "200":
              description: Success
            # responses may fall through to errors
            default:
              description: Error
              schema:
                $ref: "#/definitions/ErrorResponse"
    ...

  • ./swagger-node-slack/api/controllers/ticker.js -- これはコントローラーファイルです。特定の API パス (またはルート) に対して実行されるロジックを実装します。swagger.yaml ファイルでは、x-swagger-router-controller 属性がコントローラーファイルの名前 (.js は不要) を指定します。operationId は、/ticker パスが要求されたときに呼び出す関数の名前を指定します。したがって、この API では、/ticker API を呼び出すと、ticker.js というコントローラーファイル内の ticker() という関数が実行されます。これがコントローラーコードです。URL 変数の値は Slack から来ます。リクエストがサーバーに到着すると、Swagger 仕様によって自動的に分類され、swagger-node プロジェクトを使用すると、受信リクエストの構造に簡単にアクセスできます。たとえば、「text」という定義されたパラメータの値にアクセスするには、req.swagger.params.text.value を使用できます。コントローラーコードでは次のとおりです。

    var util = require('util');
    var request = require('request');
    var googleStocks = require('google-stocks');
    module.exports = {
      ticker: ticker
    };
    //var URL = "https://hooks.slack.com/services/GET/FROM/SLACK";
    function ticker(req, res) {
        var symbol = req.swagger.params.text.value.toUpperCase();
        googleStocks.get([symbol], function(error, data) {
            console.log(symbol+": "+data[0].l);
            var text = symbol+" is now $"+data[0].l+" per share.\nThanks for asking, @"+req.swagger.params.user_name.value+"!";
            request.post({ url:URL, body:{"text":text}, json:true});
            res.status(200).type('application/json').end();
        });
    }

Slack 統合を作成する

次に、Slack 側で統合を作成して設定する必要があります。

  1. Slack アカウントにログインします。

  2. Slack チームメニューから [統合の設定] を選択します。alt text

  3. [DYI Integrations & Customizations] までスクロールし、[Incoming WebHooks] をクリックします。

  4. [チャンネルに投稿] で、API 応答を投稿するチャンネルを選択します。つまり、誰かがティッカーボットを呼び出すたびに、株価がこのチャンネルに投稿され、全員が見ることができます。

  5. [Incoming WebHooks 統合を追加] をクリックします。

  6. 必要に応じて、設定手順を確認してください。WebHook URL に最も興味があります。

  7. WebHook URL をコピーします。ヒント: これはコントローラーファイルに追加する必要がある URL です。次のようになります。https://hooks.slack.com/services/X01234/BT1234/PSb1234abcdefghi";

  8. [カスタム名] フィールドで、デフォルト名を「Ticker-bot」に変更します。これは Slack への投稿に表示される名前です。

  9. [カスタムアイコン] UI を使用して、Slack 投稿に表示される絵文字を選択します。

コントローラーを編集する

最後に、その WebHook URL を ticker.js コントローラーファイルに追加しましょう。

  1. テキストエディタでファイル swagger-node-slack/api/controllers/ticker.js を開きます。

  2. この変数を特定し、コメントアウトを解除します: var URL = "https://hooks.slack.com/services/GET/SLACK URL";

  3. URL 変数の値を Webhook URL に置き換えます。(この URL ではなく、あなたの URL を使用してください！): var URL = "https://hooks.slack.com/services/X01234/BT1234/PSb1234abcdefghi";

  4. ファイルを保存します。

試してみる！

swagger-node で構築されたプロジェクトの優れた点の1つは、組み込みの HTTP サーバーでローカルに構築およびテストできることです。新しいティッカーボットを試してみましょう！

Incoming WebHooks 統合では、別のサービスから Slack チャンネルにメッセージを送信するという考えであることを忘れないでください。

  1. swagger-node-slack ディレクトリに移動します。

  2. 以前に実行していない場合は、このコマンドを実行して Node.js の依存関係を更新します: npm install

  3. プロジェクトを開始します: swagger project start

  4. 別のターミナルウィンドウで、次のように API を呼び出します... curl -X POST -H "Content-Type: application/x-www-form-urlencoded" https://:10010/ticker -d "text=AAPL&user_name=Will" ...すると、Slack セッションでこのようにきれいにフォーマットされた応答が返されます。

    alt text

何が起こったのか？

swagger-node バックエンド API を使用して Slack WebHooks 統合コマンドを簡単に作成できることを確認しました。API は株価サービスへのリクエストをプロキシし、Slack WebHook 統合を介して応答を Slack に投稿しました。Slack は応答を取得し、チャットウィンドウに表示しました。

次は何ですか？

もう1つのクールな Slack 統合は「スラッシュコマンド」です。Slack スラッシュコマンドを使用すると、Slack 会話に直接コマンドを入力することで関数を実行できます。

swagger-node を使用したスラッシュコマンドの例をご覧になりたい場合は、swagger-node-slack プロジェクトにアクセスしてください。このブログチュートリアルの拡張版があります。スラッシュコマンドの例では、提供したテキストを逆にするコマンドを構築します。これには、トークン検証と API をクラウドにデプロイする手順が含まれています。

したがって、Slack で次のようなことができます...

/reverse The quick brown fox jumps over the lazy dog

alt text

...すると Slack は文字を逆にして返します。

alt text

こちらもおすすめ