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

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

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

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

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

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

## SlackAppの作成
[こちら](https://api.slack.com/authentication/basics)のSlack公式の文書を元に、SlackAppを作成する手順を説明します。

- [こちら](https://api.slack.com/apps)にアクセスして[Create Slack App]ボタンを押す。
- アプリ名と対象のワークスペースを選択する。

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

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

- Web上でインストール

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

### Web上でインストール
[こちら](https://api.slack.com/authentication/basics)のSlack公式の文書を元に、Web上でインストールする手順をまとめます。

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

![ScopesAdd.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/6c9f2446-17b1-8c7a-2e6e-fb65d502efa0.png)

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

![InstallToWorkspace.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/b1f5549b-55c3-33a1-f301-c99ff2c806eb.png)

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

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

![GetAccessToken.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/8b5f7391-bb9c-f5a1-d081-5c86911ee869.png)

### OAuth2.0のバージョン2の仕組みでインストール
[こちら](https://api.slack.com/authentication/oauth-v2#obtaining)のSlack公式の文書を元に、以下に手順をまとめます。  

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

![SetRedirectURLs.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/02229667-c6ee-7b06-b793-36a393835453.png)
 

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

![GetClientSecret.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/2a2b804b-9b15-c5b8-e391-5278c888a89f.png)

- 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ブラウザで表示されるので、許可ボタンを押下する。

<img width="1056" alt="oauthImage.png" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/d4a6b8dd-a49b-25c2-7065-a36b1af6a08d.png">



- 許可ボタンを押すと、リダイレクト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タグの値がアクセストークンです。

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

![APIReference.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/452292/dce382a7-7440-7e82-a008-2119b3c099a0.png)


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