SlackAPIを使うために必要な準備

## はじめに
本文書は、SlackAPIを使うために必要な準備をまとめることを目的としています。

## SlackAPIとは
他のアプリケーションでのAPIと同様に外部アプリケーションからSlackを操作するための仕組みです。
公式資料はこちらです。
本文書では、上記資料のWeb APIを利用する際に必要な準備をまとめます。

## 準備
公式資料にも書かれていますが、SlackAPIの利用には以下が必要です。

• SlackAppの作成
• SlackAppをインストールすることで生成されるアクセストークンの取得

次節以降で上記準備の手順をそれぞれまとめていきます。

## SlackAppの作成
こちらのSlack公式の文書を元に、SlackAppを作成する手順を説明します。

• こちらにアクセスして[Create Slack App]ボタンを押す。
• アプリ名と対象のワークスペースを選択する。

以上でSlackAppの作成は完了です。

## SlackAppをインストールすることで生成されるアクセストークンの取得
SlackAppには以下の2つのインストール方法があります。
インストール方法によってアクセストークンの取得方法も違うので、それぞれのインストールとアクセストークンの取得方法を説明していきます。
なお。「OAuth2.0のバージョン2の仕組みでインストール」はSlackとは別のWebアプリケーション上からSlackAppをインストールしたい場合に主に使われます。

• Web上でインストール

• OAuth2.0のバージョン2の仕組みでインストール

### Web上でインストール
こちらのSlack公式の文書を元に、Web上でインストールする手順をまとめます。

• こちらにアクセスし、作成したアプリを選択する。
• [OAuth&Permisstions]ページでScopeタブを選択し、スコープを追加する。(スコープについては、補足情報で説明しています。)

• [OAuth&Permisstions]ページの画面上部のInstall To WorkSpaceボタンをクリック。

アクセストークンは以下の手順で取得できます。

• [OAuth&Permisstions]ページのTokens for Your Workspaceの部分にアクセストークンが表示される。

### OAuth2.0のバージョン2の仕組みでインストール
こちらのSlack公式の文書を元に、以下に手順をまとめます。  

• こちらにアクセスし、作成したアプリを選択する。  
• [OAuth&Permisstions]ページでScopeタブを選択し、スコープを追加する。
• [OAuth&Permisstions]ページのRedirect URLsにリダイレクト用URL(以後リダイレクトURLと呼ぶ)を追加する。(リダイレクトURLで指定するページの振る舞いは、後述する。)

 

• [Basic Information]ページで以下の情報を記録し、後から参照できるようにしておく。
  • Client ID (以後クライアントIDと呼ぶ)
  • Client Secret (以後クライアントシークレットと呼ぶ)

• Webブラウザで以下のURLに移動する。client_idにはクライアントIDが、redirect_urlはリダイレクトURLが入る。scopeはSlack側で設定したスコープと同じものを設定する。(以下はusers:readとchannels:readスコープを設定する場合の例)
  • https://slack.com/oauth/v2/authorize?user_scope=users:read,channels:read&client_id=xxx&redirect_uri=http://xxx
• リダイレクトしたのちにアプリをインストールするかどうかを促す画面がWebブラウザで表示されるので、許可ボタンを押下する。

• 許可ボタンを押すと、リダイレクトURLに、「code」がクエリパラメータとしてリダイレクトされる。具体的には以下のようなURLにリダイレクトされる。
  • http://xxx?code=xxxxxxx
• リダイレクトURLで指定するWebページは、以下の振る舞いを示すようにしておく。
  • 「code」パラメータの値を解釈して、ブラウザ上に「code」(以後認可コードと呼ぶ)の内容を表示する。
• 上記で取得した認可コードを使って、以下のURLにPOSTリクエストを発行する。(codeには認可コード、client_idにはクライアントID、redirect_urlにはリダイレクトURL、client_secretにはクライアントシークレットを入れる)
  • https://slack.com/api/oauth.v2.access?code=xxx&redirect_uri=http://xxx&client_id=xxx&client_secret=xxx
• 上記POSTリクエストのレスポンスがOKで返ってこれば、インストール完了。そしてレスポンスのtokenタグの値がアクセストークンです。

## 補足情報
### スコープ
公式文書はこちらです。スコープとは、SlackAppができる権限を示すものです。つまり、スコープによってSlackAppでできることが制限されています。
例えばusers:readスコープを追加すると、API経由でユーザー情報を読み取ることができるようになります。必要最低限のスコープにすることでAPI経由での不正な操作を防ぐことができるので、スコープの設定は重要になります。スコープの一覧はこちらです。
利用するAPIメソッド毎に必要なスコープが決まっており、リファレンスにも記載されているので、使いたいAPIベースでスコープを設定すれば、APIを利用するうえでは困らないと思います。
以下はチャンネルのメッセージ履歴を取得するAPIのリファレンス(リンクはこちら)のスコープについて書かれた部分です。このようにAPI毎に必要なスコープが定義されています。なお、TokenTypeについてはこちらの記事を参照ください。

## まとめ
SlackAPIを利用するうえで必要な準備をまとめました。「OAuth2.0のバージョン2の仕組みでのインストール」は、別アプリケーションからSlackAppをインストールするために用意されているようなので、手軽にAPIを試したい場合には、「Web上でインストール」をお勧めします。
API利用時には、本稿で取得したアクセストークンを使います。実際にどのように使うのかは別途記事にして投稿する予定です。