Postman を使って Slack API メソッドを呼び出してみよう

少しつづ暖かくなってきて、もうすぐ春が来ますね。春の象徴はやっぱり「さくら」🌸 ですよね。実は日本で桜を見るのが初めてで、花見をするのをとても楽しみにしています！花粉さえなければいいのですが。改めまして、Slack で Developer Relations を担当している Jason と申します。

# はじめに
このガイドでは、Slack アプリの作成と Postman を使った [Slack の OAuth フロー](https://api.slack.com/authentication)をご紹介いたします。Postman は、ユーザーやボットトークンを一度だけ取得したい場合や Slack API で遊んでみたりしたい場合におすすめです。なお、この記事は主にボットトークンの取得を中心に書かれていますが、このチュートリアルの最後には[ユーザートークンの取得方法](https://qiita.com/hello_jun/items/f4302b9f9fbbce92a562#%E7%95%AA%E5%A4%96%E7%B7%A8-%E3%83%A6%E3%83%BC%E3%82%B6%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%81%BE%E3%81%9F%E3%81%AF-org-%E3%83%AC%E3%83%99%E3%83%AB%E3%81%AE%E3%83%88%E3%83%BC%E3%82%AF%E3%83%B3%E3%82%92%E5%8F%96%E5%BE%97%E3%81%99%E3%82%8B%E6%96%B9%E6%B3%95)についても説明しています。

# 必要なもの
1. アプリをインストールできる Slack ワークスペース。ワークスペースの設定によっては Admin または Owner に承認を依頼する必要があります。特に理由がなければ、テスト用の[新しい Slack ワークスペースを作る](https://slack.com/intl/ja-jp/get-started#/createnew)ことをおすすめします。
2. OAuth フローをテストするための [Postman](https://www.postman.com/downloads/) アプリ。

# Postman でボットトークンを取得する手順

## 1. Slack アプリの作成

https://api.slack.com/apps?new_app=1

上記のリンクから Slack アプリを作成します。`From Scratch` を選択し、アプリの名前と開発に使用するワークスペースを指定してください。

## 2. クライアント ID と シークレットの取得
新しいアプリを作成すると「Basic Information」 ページに遷移するはずです。少し下にスクロールして、App Credentials セクションにある Client ID と Signing Secret を保管しておいてください。

![Client ID と Signing Secret](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/8fab9cc7-ee49-0005-6f4e-4c6c10b24d6d.png)

## 3. Postman の OAuth Callback URL を Redirect URL の指定
Redirect URL とは Slack が OAuth フローの認可確認画面から認可コードとともにユーザーをリダイレクトする URL のことです。この URL に Postman の URL を指定することで、Postman 側でその認可コードをトークンに交換してくれます。もっと詳しく知りたい方は、[OAuth のドキュメント（英語）](https://api.slack.com/authentication/oauth-v2#exchanging) をお読みください。

左側のペインで、「OAuth & Permissions（ OAuth と権限）」 をクリックし、Redirect URLs までにスクロールしてください。ここで、以下の URL を Redirect URLs のリストに追加してください。

`https://oauth.pstmn.io/v1/callback`

![Redirect URL の指定](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/4ced2ec4-fa3b-3ff9-259d-164f5162dd17.gif)

## 4. Slack アプリにスコープを付与
Slack アプリにボットユーザーを追加するためには、Slack アプリの管理画面で少なくとも一つのボットスコープを指定する必要があります。スコープを一つ以上指定することも可能です。スコープを付与するには、「OAuth & Permissions」 ページに移動し、Scopes までスクロールし、必要なスコープを追加してください。画像では例として、ボットユーザーとしてメッセージを送信するための権限である `chat:write` スコープを追加しています。

![スコープの付与](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/11a5470a-d9bc-fe6a-8193-41e608fdf75a.gif)

## 5. Postman 側の OAuth 設定
認証できる Slack アプリの作成が終わったので、次は Postman 側で OAuth クライアントの設定を行います。 Postman の [Authorization メニュー](https://learning.postman.com/docs/sending-requests/authorization/)で、Type を `OAuth 2.0` に指定してください。表示されるフォームに必要な項目を入力し、 OAuth クライアントをセットアップしましょう。

| 項目 | 値 | コメント |
|-----|----|--------|
| **Add auth data to Request Headers** | Request Headers | これは、リクエストのヘッダーにトークンが追加されることを意味します。Slack API を呼び出すときトークンをリクエストボディまたはヘッダーに追加する必要があります。|
| **Token Name** | お好きな名前を指定できます |トークンを管理するための名前です。|
| **Grant Type** | Authorization Code | 今回使用する OAuth フローでは、 Slack API が発行する認可コードを使ってトークンをリクエストします。この項目を指定することで、Postman に OAuth フローの種別を伝えます。|
| **Callback URL** | https://oauth.pstmn.io/v1/callback |「Authorize Using Browser」チェックボックスをオンにすると、この項目が自動的に入力されます。ブラウザで Postman を利用している方はここの URL が異なる場合があります。表示されている URL と[ステップ 3 の Redirect URL と同じものに指定してください。](https://qiita.com/hello_jun/items/f4302b9f9fbbce92a562#3-postman-%E3%81%AE-oauth-callback-url-%E3%82%92-redirect-url-%E3%81%AE%E6%8C%87%E5%AE%9A)|
| **Auth URL** | https://slack.com/oauth/v2/authorize | Slack の OAuth フローの最初のステップでは、ユーザーをこの URL に誘導する必要があります。この項目に設定しておくことで、Postman が自動的にこれを利用して OAuth フローを開始します。|
| **Access Token URL** | https://slack.com/api/oauth.v2.access | Slack の OAuth フローの最後のステップでは、認可コードを使って `oauth.v2.access` という API を呼び出すことで、アクセストークンを取得します。|
| **Client ID** | ステップ 2 の Client ID の値 | API を呼び出すときに、認可コードと共に使用される値です。|
| **Client Secret** | ステップ 2 の Client Secret の値 | API を呼び出すときに、認可コードと共に使用される値です。|
| **Scope** | 例：`chat:write` | OAuth のスコープをカンマで区切った文字列です。全てのスコープは、ここを参照してください。|
| **Client Authentication** | `Send client credentials in the body` | そのままで OK です。| 

すべて正しく入力されていれば、以下のようになります。

![OAuth の設定](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/addbd06c-a469-1d3a-6435-4c6742b44bec.png)


## 6. アクセストークンの取得
`Get New Access Token`（新しいアクセストークンを発行する）ボタンをクリックすると、新しいブラウザウィンドウが開き、ワークスペースへのアクセス許可を求める画面が表示されます。要求されたスコープを承認すると、自動的に Postman にリダイレクトされ、トークンが発行されるはずです。トークンの文字列は `xoxb-` で始まります。

# 番外編: ユーザトークンまたは OrG レベルのトークンを取得する方法
ユーザートークンや [OrG レベルのスコープ](https://api.slack.com/scopes?filter=user)（ `auditlogs:read` や `admin.*`で始まるスコープ）を取得する場合は Slack の OAuth フローから複数のトークンが発行されるため、上記の Postman の方法では処理できません。その場合は、以下の手順でやってみてください。

## 1. アプリを任意のワークスペースで利用できるようにする（ OrG レベルのスコープを利用したい場合のみ）
OrG レベルのスコープを付与しない場合、このステップは任意です。OrG レベルのスコープを使用するには、アプリを複数のワークスペースにインストールできるようにする必要があります。これは英語で Public Distribution と言います。この点に関する詳細は、こちらの[ドキュメント（英語）](https://api.slack.com/start/distributing/public#enabling_public_distribution) を参照してください。

この設定を有効にするには、Slack アプリの管理画面の左側のペインにある「Manage Distribution（配布の管理）」ページに遷移してください。そして、「Share Your App with Other Workspaces（アプリを他のワークスペースに共有する）」までスクロールしてください。ここに表示される項目は右に緑のチェックマークが付いているはずです。アプリにワークスペース固有の情報がハードコードされていないことを確認した上で「Remove Hard Coded Information（ハードコードされた情報の削除）」という項目をクリックしてください。最後に「Activate Public Distribution（公開配布を有効にする）」をクリックします。

## 2. 必要なユーザースコープの追加
ユーザートークンを取得する場合、「Postman でボットトークンを取得する手順」で説明した手順のうち 1〜4 のステップは同じです。ステップ 5 の Auth URL の値のみが異なります。`https://slack.com/oauth/v2/authorize?user_scope=` の後にリクエストしたい ユーザースコープをカンマ区切り文字列を追加する必要があります。例えば、`chat:write` と `admin` のスコープを付与したい場合、以下のような Auth URL を使用します。

`https://slack.com/oauth/v2/authorize?user_scope=chat:write,admin`

## 3. トークンの取得
先ほどと同じ手順で、「Get New Access Token」ボタンを押し、OAuth 画面で承認を行ってください。その後、Postman の 「Manage Access Tokens（アクセストークンの管理）」 モーダルで表示される Slack からのペイロードを確認する必要があります。ペイロードの中で `authed_user` を探してください。このオブジェクトの中に `access_token` というキーがあるはずです。その `xoxp-` から始まる文字列の値をコピーしてください。

![Postman の Manage Access Tokens ページ](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/d4f9af0e-1e43-e4f3-79e3-50a260433f0f.png)

Postman での API リクエストでは、度に一つのトークンしか使うことができません。ボットトークンがある場合、それがデフォルトになります。ボットトークンとユーザートークン両方を発行していて、API リクエストでユーザートークンを使用したいという場合は Postman の Access Token パラメーターに、そのユーザートークンを貼り付ける必要があります。

![トークンの取得](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/550365/388e5c87-c1a8-3f19-383a-3dbd674fc191.png)

## まとめ

これで、ボットトークンとユーザートークンを使って Slack API メソッドを呼び出す準備が整いました　🎉！早速お好きな API メソッドを呼び出してみてください。このチュートリアルをお読みになって、少しでもお役に立ったら嬉しいです。

ついでに、この記事は元々[英語で書いたもの](https://api.slack.com/tutorials/slack-apps-and-postman)ですが、興味があれば英語でもお読みください。

もし何か質問・ご不明な点があれば、気軽にコメントしてください。🤗

それでは、また！ 👋