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

少しつづ暖かくなってきて、もうすぐ春が来ますね。春の象徴はやっぱり「さくら」🌸 ですよね。実は日本で桜を見るのが初めてで、花見をするのをとても楽しみにしています！花粉さえなければいいのですが。改めまして、Slack で Developer Relations を担当している Jason と申します。 はじめに このガイドでは、Slack アプリの作成と Postman を使った Slack の OAuth フローをご紹介いたします。Postman は、ユーザーやボットトークンを一度だけ取得したい場合や Slack API で遊んでみたりしたい場合におすすめです。なお、この記事は主にボットトークンの取得を中心に書かれていますが、このチュートリアルの最後には ユーザートークンの取得方法についても説明しています。 必要なもの アプリをインストールできる Slack ワークスペース。ワークスペースの設定によっては Admin または Owner に承認を依頼する必要があります。特に理由がなければ、テスト用の新しい Slack ワークスペースを作ることをおすすめします。 OAuth フローをテストするための Postman アプリ。 Postman でボットトークンを取得する手順 1. Slack アプリの作成 上記のリンクから Slack アプリを作成します。From Scratch を選択し、アプリの名前と開発に使用するワークスペースを指定してください。 2. クライアント ID と シークレットの取得 新しいアプリを作成すると「Basic Information」 ページに遷移するはずです。少し下にスクロールして、App Credentials セクションにある Client ID と Signing Secret を保管しておいてください。 3. Postman の OAuth Callback URL を Redirect URL の指定 Redirect URL とは Slack が OAuth フローの認可確認画面から認可コードとともにユーザーをリダイレクトする URL のことです。この URL に Postman の URL を指定することで、Postman 側でその認可コードをトークンに交換してくれます。もっと詳しく知りたい方は、OAuth のドキュメント（英語） をお読みください。 左側のペインで、「OAuth & Permissions（ OAuth と権限）」 をクリックし、Redirect URLs までにスクロールしてください。ここで、以下の URL を Redirect URLs のリストに追加してください。 https://oauth.pstmn.io/v1/callback 4. Slack アプリにスコープを付与 Slack アプリにボットユーザーを追加するためには、Slack アプリの管理画面で少なくとも一つのボットスコープを指定する必要があります。スコープを一つ以上指定することも可能です。スコープを付与するには、「OAuth & Permissions」 ページに移動し、Scopes までスクロールし、必要なスコープを追加してください。画像では例として、ボットユーザーとしてメッセージを送信するための権限である chat:write スコープを追加しています。 5. Postman 側の OAuth 設定 認証できる Slack アプリの作成が終わったので、次は Postman 側で OAuth クライアントの設定を行います。 Postman の 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」チェックボックスをオンにすると、この項目が自動的に入力されます。ステップ 3 の Redirect URL と同じものです。 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 です。 すべて正しく入力されていれば、以下のようになります。 6. アクセストークンの取得 Get New Access Token（新しいアクセストークンを発行する）ボタンをクリックすると、新しいブラウザウィンドウが開き、ワークスペースへのアクセス許可を求める画面が表示されます。要求されたスコープを承認すると、自動的に Postman にリダイレクトされ、トークンが発行されるはずです。トークンの文字列は xoxb- で始まります。 番外編: ユーザトークンまたは OrG レベルのトークンを取得する方法 ユーザートークンや OrG レベルのスコープ（ auditlogs:read や admin.*で始まるスコープ）を取得する場合は Slack の OAuth フローから複数のトークンが発行されるため、上記の Postman の方法では処理できません。その場合は、以下の手順でやってみてください。 1. アプリを任意のワークスペースで利用できるようにする（ OrG レベルのスコープを利用したい場合のみ） OrG レベルのスコープを付与しない場合、このステップは任意です。OrG レベルのスコープを使用するには、アプリを複数のワークスペースにインストールできるようにする必要があります。これは英語で 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 での API リクエストでは、度に一つのトークンしか使うことができません。ボットトークンがある場合、それがデフォルトになります。ボットトークンとユーザートークン両方を発行していて、API リクエストでユーザートークンを使用したいという場合は Postman の Access Token パラメーターに、そのユーザートークンを貼り付ける必要があります。 まとめ これで、ボットトークンとユーザートークンを使って Slack API メソッドを呼び出す準備が整いました　🎉！早速お好きな API メソッドを呼び出してみてください。このチュートリアルをお読みになって、少しでもお役に立ったら嬉しいです。 ついでに、この記事は元々英語で書いたものですが、興味があれば英語でもお読みください。 もし何か質問・ご不明な点があれば、気軽にコメントしてください。🤗 それでは、また！ 👋