From 9623c96204cc2bef8059f3e37cbc769fb9e2ec89 Mon Sep 17 00:00:00 2001 From: hirosassa Date: Wed, 4 Aug 2021 23:59:20 +0900 Subject: [PATCH 1/2] add socket mode and http doc in japanese --- docs/_tutorials/getting_started_http.md | 2 +- docs/_tutorials/ja_getting_started.md | 131 +++++---- docs/_tutorials/ja_getting_started_http.md | 310 +++++++++++++++++++++ 3 files changed, 375 insertions(+), 68 deletions(-) create mode 100644 docs/_tutorials/ja_getting_started_http.md diff --git a/docs/_tutorials/getting_started_http.md b/docs/_tutorials/getting_started_http.md index 4962e46da..3882f6d9c 100644 --- a/docs/_tutorials/getting_started_http.md +++ b/docs/_tutorials/getting_started_http.md @@ -304,4 +304,4 @@ Now that you have a basic app up and running, you can start exploring how to mak * Bolt allows you to [call Web API methods](/bolt-python/concepts#web-api) with the client attached to your app. There are [over 220 methods](https://api.slack.com/methods) on our API site. -* Learn more about the different token types [on our API site](https://api.slack.com/docs/token-types). Your app may need different tokens depending on the actions you want it to perform. If you are using Socket Mode instead of HTTP, an additional (`xapp`) token with `connections:write` scopes is required. \ No newline at end of file +* Learn more about the different token types [on our API site](https://api.slack.com/docs/token-types). Your app may need different tokens depending on the actions you want it to perform. If you are using Socket Mode instead of HTTP, an additional (`xapp`) token with `connections:write` scopes is required. diff --git a/docs/_tutorials/ja_getting_started.md b/docs/_tutorials/ja_getting_started.md index 6c90c4809..3bc52993e 100644 --- a/docs/_tutorials/ja_getting_started.md +++ b/docs/_tutorials/ja_getting_started.md @@ -17,6 +17,8 @@ redirect_from: この手順を全て終わらせたら、あなたはきっと ⚡️[Slack アプリのはじめ方](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)のサンプルアプリを動作させたり、それに変更を加えたり、自分のアプリを作ったりすることができるようになるでしょう。 +> 💡 このガイドでは、[Socket Mode](https://api.slack.com/apis/connections/socket) を利用します。Socket Modeを使い始めるオススメの方法は、あなたのチームの為に何かを作ることです。すでにあなたのアプリがHTTPの通信プロトコルを利用したいとわかっている場合には、このドキュメントと並列する [Getting Started over HTTP](/bolt-python/tutorial/getting-started-http) を参照してください。 + --- ### アプリを作成する @@ -26,7 +28,7 @@ redirect_from: アプリ名を入力し（_後で変更可能_）、インストール先のワークスペースを選択したら、「`Create App`」ボタンをクリックすると、アプリの **Basic Information** ページが表示されます。 -このページでは、アプリの概要を確認できます。また、「**App Credentials**」ヘッダーの下では「`Signing Secret`」などの重要な認証情報も確認できます。これらの認証情報は後で必要になります。 +このページでは、アプリの概要や、重要な認証情報も確認できます。この情報は後ほど参照します。 ![Basic Information ページ](../../assets/basic-information-page.png "Basic Information ページ") @@ -37,25 +39,32 @@ redirect_from: ### トークンとアプリのインストール Slack アプリでは、[Slack API へのアクセスの管理に OAuth を使用します](https://api.slack.com/docs/oauth)。アプリがインストールされると、トークンが発行されます。アプリはそのトークンを使って API メソッドを呼び出すことができます。 -Slack アプリで使用できるトークンには、ユーザートークン（`xoxp`）とボットトークン（`xoxb`）の 2 種類があります。ユーザートークンを使用すると、ユーザーがアプリをインストールまたは認証した後、アプリがそのユーザーを代理して API メソッドを呼び出すことができます。1 つのワークスペースに複数のユーザートークンが存在する可能性があります。ボットトークンはボットユーザーに関連づけられ、1 つのワークスペースでは最初に誰かがそのアプリをインストールした際に一度だけ発行されます。どのユーザーがインストールを実行しても、アプリが使用するボットトークンは同じになります。_ほとんど_のアプリで使用されるのは、ボットトークンです。 +Slack アプリで使用できるトークンには、ユーザートークン（`xoxp`）とボットトークン（`xoxb`）、アプリレベルトークン（`xapp`）の 3 種類があります。 +- [ユーザートークン](https://api.slack.com/authentication/token-types#user) を使用すると、ユーザーがアプリをインストールまたは認証した後、アプリがそのユーザーを代理して API メソッドを呼び出すことができます。1 つのワークスペースに複数のユーザートークンが存在する可能性があります。 +- [ボットトークン](https://api.slack.com/authentication/token-types#bot) はボットユーザーに関連づけられ、1 つのワークスペースでは最初に誰かがそのアプリをインストールした際に一度だけ発行されます。どのユーザーがインストールを実行しても、アプリが使用するボットトークンは同じになります。_ほとんど_のアプリで使用されるのは、ボットトークンです。 +- [アプリレベルトークン](https://api.slack.com/authentication/token-types#app) は、組織に渡ってあなたのアプリを表すものです。所属する組織内の全てのワークスペースに、全ての個人ユーザによってインストールされたアプリについても同様です。アプリレベルトークンは、ウェブソケット通信を行うアプリを作る際に通常使われます。 -説明を簡潔にするために、このガイドではボットトークンを使用します。 +このガイドではボットトークンとアプリレベルトークンを使用します。 -左サイドバーの「**OAuth & Permissions**」をクリックし、「**Bot Token Scopes**」セクションまで下にスクロールします。「**Add an OAuth Scope**」をクリックします。 +1. 左サイドバーの「**OAuth & Permissions**」をクリックし、「**Bot Token Scopes**」セクションまで下にスクロールします。「**Add an OAuth Scope**」をクリックします。 -ここでは [`chat:write`](https://api.slack.com/scopes/chat:write) というスコープのみを追加します。このスコープは、アプリが参加しているチャンネルにメッセージを投稿することを許可します。 +2. ここでは [`chat:write`](https://api.slack.com/scopes/chat:write) というスコープのみを追加します。このスコープは、アプリが参加しているチャンネルにメッセージを投稿することを許可します。 -OAuth & Permissions ページの一番上までスクロールし、「**Install App to Workspace**」をクリックします。Slack の OAuth 確認画面 が表示されます。この画面で開発用ワークスペースへのアプリのインストールを承認します。 +3. OAuth & Permissions ページの一番上までスクロールし、「**Install App to Workspace**」をクリックします。Slack の OAuth 確認画面 が表示されます。この画面で開発用ワークスペースへのアプリのインストールを承認します。 -インストールを承認すると **OAuth & Permissions** ページが表示され、**Bot User OAuth Access Token** を確認できるでしょう。 +4. インストールを承認すると **OAuth & Permissions** ページが表示され、**Bot User OAuth Access Token** を確認できるでしょう。 ![OAuth トークン](../../assets/bot-token.png "ボット用 OAuth トークン") +5. 次に「**Basic Informationのページ**」まで戻り、アプリトークンのセクションまで下にスクロールし「**Generate Token and Scopes**」をクリックしてアプリレベルトークンを作成します。このトークンに `connections:write` のスコープを付与し、作成された `xapp`トークンを保存します。これらのトークンはこのあと利用します。 + +6. 左サイドメニューの「**Socket Mode**」を有効にします。 + > 💡 トークンはパスワードと同様に取り扱い、[安全な方法で保管してください](https://api.slack.com/docs/oauth-safety)。アプリはこのトークンを使って Slack ワークスペースで投稿をしたり、情報の取得をしたりします。 --- -### ローカルでプロジェクトをセットアップする +### プロジェクトをセットアップする 初期設定が終わったら、新しい Bolt プロジェクトのセットアップを行いましょう。このプロジェクトが、あなたのアプリのロジックを処理するコードを配置する場所となります。 プロジェクトをまだ作成していない場合は、新しく作成しましょう。空のディレクトリを作成します。 @@ -79,18 +88,21 @@ which python3 # 出力結果 : /path/to/first-bolt-app/.venv/bin/python3 ``` -Bolt for Python のパッケージを新しいプロジェクトにインストールする前に、アプリの設定時に作成されたボットトークンと署名シークレットを保存しましょう。これらは環境変数に保存する必要があります。バージョンコントロールには*保存しない*ようにしてください。 +Bolt for Python のパッケージを新しいプロジェクトにインストールする前に、アプリの設定時に作成された **ボットトークン** と **アプリレベルトークン** を保存しましょう。 -1. **Basic Information ページの署名シークレット（Signing Secret）をコピー**して、新しい環境変数に保存します。以下のコマンド例は Linux と macOS で利用できます。[Windows でもこれに似たコマンドが利用できます](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153)。 +1. **OAuth & Permissions ページのボットトークン (xoxb) をコピー**して、新しい環境変数に保存します。以下のコマンド例は Linux と macOS で利用できます。[Windows でもこれに似たコマンドが利用できます](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153)。 ```shell -export SLACK_SIGNING_SECRET=<署名シークレット> +export SLACK_BOT_TOKEN=xoxb- ``` -2. **OAuth & Permissions ページのボットトークン（xoxb）をコピー**して、別の環境変数に保存します。 +2. **OAuth & Permissions ページのアプリレベルトークン（xapp）をコピー**して、別の環境変数に保存します。 ```shell -export SLACK_BOT_TOKEN=xoxb-<ボットトークン> +export SLACK_APP_TOKEN= ``` +> 🔒 全てのトークンは安全に保管してください。最低限、パブリックなバージョンコントロールにチェックインすることは避けてください。また、上記の例のように環境変数を介してアクセスするようにしてください。詳細な情報は [best practices for app security](https://api.slack.com/authentication/best-practices).のドキュメントを参照してください。 + + 完了したら、アプリを作ってみましょう。以下のコマンドを使って、仮想環境に Python の `slack_bolt` パッケージをインストールします。 ```shell @@ -102,57 +114,42 @@ pip install slack_bolt ```python import os from slack_bolt import App +from slack_bolt.adapter.socket_mode import SocketModeHandler -# ボットトークンと署名シークレットを使ってアプリを初期化します -app = App( - token=os.environ.get("SLACK_BOT_TOKEN"), - signing_secret=os.environ.get("SLACK_SIGNING_SECRET") -) +# ボットトークンとソケットモードハンドラーを使ってアプリを初期化します +app = App(token=os.environ.get("SLACK_BOT_TOKEN")) # アプリを起動します if __name__ == "__main__": - app.start(port=int(os.environ.get("PORT", 3000))) + SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start() ``` -このようにトークンと署名シークレットだけあれば、最初の Bolt アプリが作成できます。「`app.py`」ファイルを保存して、コマンドラインで以下を実行します。 +このようにトークンがあれば、最初の Bolt アプリが作成できます。「`app.py`」ファイルを保存して、コマンドラインで以下を実行します。 ```script python3 app.py ``` -アプリが起動し、実行中であることが表示されます。 +アプリが起動し、実行中であることが表示されます。🎉 --- ### イベントを設定する -アプリはワークスペース内の他のメンバーと同じように振る舞い、メッセージを投稿したり絵文字リアクションを追加したりできます。Slack ワークスペースで発生するイベント（メッセージが投稿されたときや、メッセージに対するリアクションがつけられたときなど）をリッスンするには、[Events API を使って特定の種類のイベントをサブスクライブします](https://api.slack.com/events-api)。 +アプリはワークスペース内の他のメンバーと同じように振る舞い、メッセージを投稿したり、絵文字リアクションを追加したり、イベントをリッスンして返答したりできます。 -アプリをイベントに対応させるため、まずこのアプリの設定ページに戻って設定を行います。[アプリ管理ページ](https://api.slack.com/apps)でアプリをクリックします。次に、左サイドバーの「**Event Subscriptions**」をクリックします。「**Enable Events**」というラベルのスイッチをオンに切り替えます。 +Slack ワークスペースで発生するイベント（メッセージが投稿されたときや、メッセージに対するリアクションがつけられたときなど）をリッスンするには、[Events API を使って特定の種類のイベントをサブスクライブします](https://api.slack.com/events-api)。 -「**Request URL**」というラベルのテキスト入力フィールドが表示されます。Request URL は、指定したイベントに対応する Slack からの HTTP POST リクエストの送信先となるパブリック URL です。 +> 💡 このチュートリアルの序盤でソケットモードを有効にしました。ソケットモードを使うことで、アプリがパブリックなHTTPエンドポイントを公開せず、イベントAPIやインタラクティブコンポーネントを利用できるようになります。このことは、開発時やファイヤーウォールの裏からのリクエストを受ける際に便利です。HTTPはホスティングされた環境にデプロイされたアプリや、Slack App Directoryで配布されるアプリに向いています。これらの情報については、[このドキュメント](/bolt-python/tutorial/getting-started-http).を参照してください。 -> ⚙️ [API サイト](https://api.slack.com/docs/hosting)に、Slack の開発チームがアプリのホストによく使用する一般的なホスティングプロバイダをいくつか記載しておきました。 +それでは、Slackにどのイベントをリッスンするかを教えてあげましょう。 イベントが発生すると、そのイベントをトリガーしたユーザーやイベントが発生したチャンネルなど、イベントに関する情報が Slack からアプリに送信されます。アプリではこれらの情報を処理して、適切な応答を返します。 -
- -

開発用にローカルの Request URL を使用する

- アプリの開発を始めたばかりの場合、パブリックにアクセスできる URL をまだ持っていないかもしれませんね。最終的には適切なものをセットアップするものとして、ここでは [ngrok](https://ngrok.com/) のような開発用プロキシを利用することにします。開発用プロキシを利用すると、リクエストを開発環境にトンネルするパブリック URL を作成できます。[Slack のローカル開発で ngrok を使用する方法](https://api.slack.com/tutorials/tunneling-with-ngrok)については、別のチュートリアルを用意していますので参考にしてください。開発用プロキシをインストールして実行を開始すると、リクエストが特定のポートに転送されるようになります（この例ではポート 3000 を使用していますが、アプリを初期化する際に使用ポートをカスタマイズしている場合は、そのポートを使用してください）。```shell ngrok http 3000 ``` ![ngrok の実行](../../assets/ngrok.gif "ngrok の実行") 利用可能な URL が生成され、出力結果に表示されます（「`https://`」で始まる URL をおすすめします）。この URL がリクエスト URL のベースになります。この例では「`https://8e8ec2d7.ngrok.io`」です。--- -
- -これで、ローカルマシンにトンネルしてアプリで利用できるパブリック URL が用意できました。アプリの設定で指定する Request URL は、パブリック URL に、アプリがリッスンするパスを組み合わせたものになります。デフォルトでは、Bolt アプリは「`/slack/events`」をリッスンします。この場合、Request URL 全体は「`https://8e8ec2d7.ngrok.io/slack/events`」となります。 - -> ⚙️ Bolt では、`/slack/events` というエンドポイントで、すべての受信リクエストをリッスンします。これらのリクエストにはショートカット、イベント、インタラクションペイロードが含まれます。アプリの設定でエンドポイントを指定するときは、すべての Request URL の末尾に「`/slack/events`」を追加してください。 - -「**Request URL**」ボックスの「**Enable Events**」スイッチの下に URL を貼りつけます。Bolt アプリが起動した状態のままなら、URL の検証が成功するはずです。 - -Request URL の検証が完了したら、「**Subscribe to Bot Events**」まで下にスクロールします。メッセージに関連するイベントには、次の 4 つがあります。 - -- `message.channels` アプリが参加しているパブリックチャンネルのメッセージをリッスン -- `message.groups` アプリが参加しているプライベートチャンネルのメッセージをリッスン -- `message.im` あなたのアプリとユーザーのダイレクトメッセージをリッスン -- `message.mpim` あなたのアプリが追加されているグループ DM をリッスン +**Subscribe to Bot Events** まで下にスクロールします。4つのメッセージに関するイベントがあります。 +- [`message.channels`](https://api.slack.com/events/message.channels) アプリが参加しているパブリックチャンネルのメッセージをリッスン +- [`message.groups`](https://api.slack.com/events/message.groups) アプリが参加しているプライベートチャンネルのメッセージをリッスン +- [`message.im`](https://api.slack.com/events/message.im) あなたのアプリとユーザーのダイレクトメッセージをリッスン +- [`message.mpim`](https://api.slack.com/events/message.mpim) あなたのアプリが追加されているグループ DM をリッスン ボットが参加するすべての場所のメッセージをリッスンさせるには、これら 4 つのメッセージイベントをすべて選択します。ボットにリッスンさせるメッセージイベントの種類を選択したら、「**Save Changes**」ボタンをクリックします。 @@ -166,12 +163,10 @@ Request URL の検証が完了したら、「**Subscribe to Bot Events**」ま ```python import os from slack_bolt import App +from slack_bolt.adapter.socket_mode import SocketModeHandler -# ボットトークンと署名シークレットを使ってアプリを初期化します -app = App( - token=os.environ.get("SLACK_BOT_TOKEN"), - signing_secret=os.environ.get("SLACK_SIGNING_SECRET") -) +# ボットトークンとソケットモードハンドラーを使ってアプリを初期化します +app = App(token=os.environ.get("SLACK_BOT_TOKEN")) # 'hello' を含むメッセージをリッスンします # 指定可能なリスナーのメソッド引数の一覧は以下のモジュールドキュメントを参考にしてください： @@ -183,7 +178,7 @@ def message_hello(message, say): # アプリを起動します if __name__ == "__main__": - app.start(port=int(os.environ.get("PORT", 3000))) + SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start() ``` アプリを再起動し、ボットユーザーが参加しているチャンネルまたはダイレクトメッセージに「hello」というメッセージを投稿すれば、アプリが応答するでしょう。 @@ -194,27 +189,25 @@ if __name__ == "__main__": ### アクションを送信して応答する -インタラクティブ機能を有効にすると、ボタン、選択メニュー、日付ピッカー、モーダル、ショートカットなどの機能が利用できるようになります。イベントと同様に、Slack からのアクション（*ユーザーがボタンをクリックした*など）の送信先となる URL を設定する必要があります。 +インタラクティブ機能を有効にすると、ボタン、選択メニュー、日付ピッカー、モーダル、ショートカットなどの機能が利用できるようになります。アプリ設定ページの「**Interactivity & Shortcuts**」を見てみましょう。 -アプリ設定ページに戻り、左サイドメニューの「**Interactivity & Shortcuts**」をクリックします。別の **Request URL** ボックスを見つけます。 +> 💡 ソケッットモードを有効にしていると、デフォルトで、基本的なインタラクティブ機能が有効になっていることに気づくでしょう。追加のアクションは不要です。HTTPを使っている場合は、Slackに対して、イベントを送信する為のリクエストURLを設定する必要があります。 -デフォルトでは、Bolt はイベントに使用しているのと同じエンドポイントをインタラクティブコンポーネントにも使用するように設定されているため、上記と同じリクエスト URL（この例では「`https://8e8ec2d7.ngrok.io/slack/events`」）を使用します。このままの状態で、右下隅にある「**Save Changes**」ボタンを押してください。これでインタラクティブ機能がアプリで利用できるようになりました。 +インタラクティブ機能が有効化されている時、ショートカット、モーダル、インタラクティブコンポーネント (ボタンや、選択メニュー、日付ピッカー) とのインタラクションはイベントとしてアプリに対して送信されます。 -![Request URL の設定](../../assets/request-url-config.png "Request URL の設定") - -それでは、アプリのコードに戻り、インタラクティブ機能を追加しましょう。インタラクティブ機能は 2 つのステップで構成されます。まず、ボタンを含んだメッセージをアプリから送信します。次に、ユーザーから返されるボタンクリックのアクションをリッスンし、それに応答します。 +それでは、アプリのコードに戻り、これらのイベントを処理する為のロジックを追加しましょう。 +- まず、ボタンを含んだメッセージをアプリから送信します。 +- 次に、ユーザーから返されるボタンクリックのアクションをリッスンし、それに応答します。 以下のコードの後の部分を編集し、文字列だけのメッセージの代わりに、ボタンを含んだメッセージを送信するようにしてみます。 ```python import os from slack_bolt import App +from slack_bolt.adapter.socket_mode import SocketModeHandler -# ボットトークンと署名シークレットを使ってアプリを初期化します -app = App( - token=os.environ.get("SLACK_BOT_TOKEN"), - signing_secret=os.environ.get("SLACK_SIGNING_SECRET") -) +# ボットトークンとソケットモードハンドラーを使ってアプリを初期化します +app = App(token=os.environ.get("SLACK_BOT_TOKEN")) # 'hello' を含むメッセージをリッスンします @app.message("hello") @@ -235,9 +228,15 @@ def message_hello(message, say): text=f"Hey there <@{message['user']}>!" ) +@app.action("button_click") +def action_button_click(body, ack, say): + # Acknowledge the action + ack() + say(f"<@{body['user']['id']}> clicked the button") + # アプリを起動します if __name__ == "__main__": - app.start(port=int(os.environ.get("PORT", 3000))) + SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start() ``` `say()` の中の値を `blocks` という配列のオブジェクトに変えました。ブロックは Slack メッセージを構成するコンポーネントであり、テキストや画像、日付ピッカーなど、さまざまなタイプのブロックがあります。この例では `accessory` に `button` を持たせた「section」のブロックを、アプリからの応答に含めています。`blocks` を使用する場合、`text` は通知やアクセシビリティのためのフォールバックとなります。 @@ -253,12 +252,10 @@ if __name__ == "__main__": ```python import os from slack_bolt import App +from slack_bolt.adapter.socket_mode import SocketModeHandler # ボットトークンと署名シークレットを使ってアプリを初期化します -app = App( - token=os.environ.get("SLACK_BOT_TOKEN"), - signing_secret=os.environ.get("SLACK_SIGNING_SECRET") -) +app = App(token=os.environ.get("SLACK_BOT_TOKEN")) # 'hello' を含むメッセージをリッスンします @app.message("hello") @@ -296,11 +293,11 @@ if __name__ == "__main__": --- ### 次のステップ -はじめての [Bolt for Python アプリ](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)を構築することができました。🎉 +はじめての [Bolt for Python アプリ](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)をソケットモードを使って構築することができました。🎉 ここまでで基本的なアプリをセットアップして実行することはできたので、次は自分だけの Bolt アプリを作る方法を調べてみましょう。参考になりそうな記事をいくつかご紹介します。 * [基本的な概念](/bolt-python/concepts#basic)について読む。Bolt アプリがアクセスできるさまざまメソッドや機能について知ることができます。 * [`events()` メソッド](/bolt-python/concepts#event-listening)でボットがリッスンできるイベントをほかにも試してみる。すべてのイベントの一覧は [API サイト](https://api.slack.com/events)で確認できます。 * Bolt では、アプリにアタッチされたクライアントから [Web API メソッドを呼び出す](/bolt-python/concepts#web-api)ことができます。API サイトに [220 以上のメソッド](https://api.slack.com/methods)を一覧しています。 -* [API サイト](https://api.slack.com/docs/token-types)でほかのタイプのトークンを確認する。アプリで実行したいアクションによって、異なるトークンが必要になる場合があります。 \ No newline at end of file +* [API サイト](https://api.slack.com/docs/token-types)でほかのタイプのトークンを確認する。アプリで実行したいアクションによって、異なるトークンが必要になる場合があります。ソケットモードを使わないアプリでは、通常はボットトークン (`xoxb`) と署名シークレットが必要です。これについての例は、このチュートリアルと並列する [Getting Started with HTTP](/bolt-python/tutorial/getting-started-http) を参照してください。 diff --git a/docs/_tutorials/ja_getting_started_http.md b/docs/_tutorials/ja_getting_started_http.md new file mode 100644 index 000000000..632776f68 --- /dev/null +++ b/docs/_tutorials/ja_getting_started_http.md @@ -0,0 +1,310 @@ +--- +title: Bolt 入門ガイド HTTP +order: 5 +slug: getting-started-http +lang: ja-jp +layout: tutorial +permalink: /ja-jp/tutorial/getting-started-http +redirect_from: + - /ja-jp/getting-started-http + - /getting-started-http/ja-jp +--- +# Bolt 入門ガイド HTTP + +
+このガイドでは、**HTTP上で Bolt for Python** を使った Slack アプリの設定と起動する方法について説明します。ここで説明する手順は、新しい Slack アプリを作成し、ローカルの開発環境をセットアップし、Slack ワークスペースからのメッセージをリッスンして応答するアプリを開発するという流れになります。 +
+ +この手順を全て終わらせたら、あなたはきっと ⚡️[Slack アプリのはじめ方](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)のサンプルアプリを動作させたり、それに変更を加えたり、自分のアプリを作ったりすることができるようになるでしょう。 + +--- + +### アプリを作成する +最初にやるべきこと : Bolt での開発を始める前に、[Slack アプリを作成](https://api.slack.com/apps/new)します。 + +> 💡 いつもの仕事のさまたげにならないように、別の開発用のワークスペースを使用することをおすすめします。[新しいワークスペースは無料で作成できます](https://slack.com/get-started#create)。 + +アプリ名を入力し（_後で変更可能_）、インストール先のワークスペースを選択したら、「`Create App`」ボタンをクリックすると、アプリの **Basic Information** ページが表示されます。 + +このページでは、アプリの概要を確認できます。また、「**App Credentials**」ヘッダーの下では「`Signing Secret`」などの重要な認証情報も確認できます。これらの認証情報は後で必要になります。 + + +![Basic Information ページ](../../assets/basic-information-page.png "Basic Information ページ") + +ひと通り確認し、アプリのアイコンと説明を追加したら、アプリの構成 🔩 を始めましょう。 + +--- + +### トークンとアプリのインストール +Slack アプリでは、[Slack API へのアクセスの管理に OAuth を使用します](https://api.slack.com/docs/oauth)。アプリがインストールされると、トークンが発行されます。アプリはそのトークンを使って API メソッドを呼び出すことができます。 + +Slack アプリで使用できるトークンには、ユーザートークン（`xoxp`）とボットトークン（`xoxb`）、アプリレベルトークン（`xapp`）の 3 種類があります。 +- [ユーザートークン](https://api.slack.com/authentication/token-types#user) を使用すると、ユーザーがアプリをインストールまたは認証した後、アプリがそのユーザーを代理して API メソッドを呼び出すことができます。1 つのワークスペースに複数のユーザートークンが存在する可能性があります。 +- [ボットトークン](https://api.slack.com/authentication/token-types#bot) はボットユーザーに関連づけられ、1 つのワークスペースでは最初に誰かがそのアプリをインストールした際に一度だけ発行されます。どのユーザーがインストールを実行しても、アプリが使用するボットトークンは同じになります。_ほとんど_のアプリで使用されるのは、ボットトークンです。 +- [アプリレベルトークン](https://api.slack.com/authentication/token-types#app) は、組織に渡ってあなたのアプリを表すものです。所属する組織内の全てのワークスペースに、全ての個人ユーザによってインストールされたアプリについても同様です。アプリレベルトークンは、ウェブソケット通信を行うアプリを作る際に通常使われます。 + +説明を簡潔にするために、このガイドではボットトークンを使用します。 + +1. 左サイドバーの「**OAuth & Permissions**」をクリックし、「**Bot Token Scopes**」セクションまで下にスクロールします。「**Add an OAuth Scope**」をクリックします。 + +2. ここでは [`chat:write`](https://api.slack.com/scopes/chat:write) というスコープのみを追加します。このスコープは、アプリが参加しているチャンネルにメッセージを投稿することを許可します。 + +3. OAuth & Permissions ページの一番上までスクロールし、「**Install App to Workspace**」をクリックします。Slack の OAuth 確認画面 が表示されます。この画面で開発用ワークスペースへのアプリのインストールを承認します。 + +4. インストールを承認すると **OAuth & Permissions** ページが表示され、**Bot User OAuth Access Token** を確認できるでしょう。このトークンはこのあと利用します。 + +![OAuth トークン](../../assets/bot-token.png "ボット用 OAuth トークン") + +> 💡 トークンはパスワードと同様に取り扱い、[安全な方法で保管してください](https://api.slack.com/docs/oauth-safety)。アプリはこのトークンを使って Slack ワークスペースで投稿をしたり、情報の取得をしたりします。 + +--- + +### プロジェクトをセットアップする +初期設定が終わったら、新しい Bolt プロジェクトのセットアップを行いましょう。このプロジェクトが、あなたのアプリのロジックを処理するコードを配置する場所となります。 + +プロジェクトをまだ作成していない場合は、新しく作成しましょう。空のディレクトリを作成します。 + +```shell +mkdir first-bolt-app +cd first-bolt-app +``` + +次に、プロジェクトの依存関係を管理する方法として、[Python 仮想環境](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment)を使ったおすすめの方法を紹介します。これはシステム Python に存在するパッケージとのコンフリクトを防ぐために推奨されている優れた方法です。[Python 3.6 以降](https://www.python.org/downloads/)の仮想環境を作成し、アクティブにしてみましょう。 + +```shell +python3 -m venv .venv +source .venv/bin/activate +``` + +`python3` へのパスがプロジェクトの中を指していることを確かめることで、仮想環境がアクティブになっていることを確認できます（[Windows でもこれに似たコマンドが利用できます](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/#activating-a-virtual-environment)）。 + +```shell +which python3 +# 出力結果 : /path/to/first-bolt-app/.venv/bin/python3 +``` + +Bolt for Python のパッケージを新しいプロジェクトにインストールする前に、アプリの設定時に作成された **ボットトークン** と **署名シークレット** を保存しましょう。 + +1. **OAuth & Permissions ページの署名シークレットをコピー**して、新しい環境変数に保存します。以下のコマンド例は Linux と macOS で利用できます。[Windows でもこれに似たコマンドが利用できます](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153)。 +```shell +export SLACK_SIGNING_SECRET= +``` + +2. **OAuth & Permissions ページのボットトークン (xoxb) をコピー**して、新しい環境変数に保存します。以下のコマンド例は Linux と macOS で利用できます。[Windows でもこれに似たコマンドが利用できます](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153)。 +```shell +export SLACK_BOT_TOKEN=xoxb- +``` + +> 🔒 全てのトークンは安全に保管してください。最低限、パブリックなバージョンコントロールにチェックインすることは避けてください。また、上記の例のように環境変数を介してアクセスするようにしてください。詳細な情報は [best practices for app security](https://api.slack.com/authentication/best-practices).のドキュメントを参照してください。 + + +完了したら、アプリを作ってみましょう。以下のコマンドを使って、仮想環境に Python の `slack_bolt` パッケージをインストールします。 + +```shell +pip install slack_bolt +``` + +このディレクトリに「`app.py`」という名前の新しいファイルを作成し、以下のコードを追加します。 + +```python +import os +from slack_bolt import App +from slack_bolt.adapter.socket_mode import SocketModeHandler + +# ボットトークンと署名シークレットを使ってアプリを初期化します +app = App( + token=os.environ.get("SLACK_BOT_TOKEN"), + signing_secret=os.environ.get("SLACK_SIGNING_SECRET") +) + +# アプリを起動します +if __name__ == "__main__": + app.start(port=int(os.environ.get("PORT", 3000))) +``` + +このようにトークンがあれば、最初の Bolt アプリが作成できます。「`app.py`」ファイルを保存して、コマンドラインで以下を実行します。 + +```script +python3 app.py +``` + +アプリが起動し、実行中であることが表示されます。🎉 + +--- + +### HTTPを利用したイベントを設定する +アプリはワークスペース内の他のメンバーと同じように振る舞い、メッセージを投稿したり、絵文字リアクションを追加したり、イベントをリッスンして返答したりできます。 + +Slack ワークスペースで発生するイベント（メッセージが投稿されたときや、メッセージに対するリアクションがつけられたときなど）をリッスンするには、[Events API を使って特定の種類のイベントをサブスクライブします](https://api.slack.com/events-api)。 + +それでは、アプリのイベント設定を有効化してみましょう。 + +1. [アプリ管理ページ](https://api.slack.com/apps)でアプリをクリックします。次に、左サイドバーの「**Event Subscriptions**」をクリックします。「**Enable Events**」というラベルのスイッチをオンに切り替えます。 +2. リクエストURLを追加します。Slackはイベントに対応するHTTP POSTリクエストをこの [Request URL](https://api.slack.com/apis/connections/events-api#the-events-api__subscribing-to-event-types__events-api-request-urls) のエンドポイントに送信します。Bolt は `/slack/events` のエンドポイントで、全ての受信リクエストをリッスンします。これらのリクエストにはショートカット、イベント、インタラクションペイロードが含まれます。アプリの設定でエンドポイントを指定するときは、すべての Request URL の末尾に「/slack/events」を追加してください。例えば、 `https:///slack/events` のようになります。Bolt アプリが起動した状態のままなら、URL の検証が成功するはずです。 + +> 💡 ローカルでの開発時には、ngrok のような開発用プロキシサービスを利用することができます。開発用プロキシを利用すると、リクエストを開発環境にトンネルするパブリック URL を作成できます。[Slack のローカル開発で ngrok を使用する方法](https://api.slack.com/tutorials/tunneling-with-ngrok)については、別のチュートリアルを用意していますので参考にしてください。また、アプリのホスティングが必要になった場合には、[API サイトに](https://api.slack.com/docs/hosting) Slack開発者達がアプリのホスティングよく利用するホスティングプロバイダーを集めています。 + +それでは、Slackにどのイベントをリッスンするかを教えてあげましょう。 + +イベントが発生すると、そのイベントをトリガーしたユーザーやイベントが発生したチャンネルなど、イベントに関する情報が Slack からアプリに送信されます。アプリではこれらの情報を処理して、適切な応答を返します。 + +**Subscribe to Bot Events** まで下にスクロールします。4つのメッセージに関するイベントがあります。 +- [`message.channels`](https://api.slack.com/events/message.channels) アプリが参加しているパブリックチャンネルのメッセージをリッスン +- [`message.groups`](https://api.slack.com/events/message.groups) アプリが参加しているプライベートチャンネルのメッセージをリッスン +- [`message.im`](https://api.slack.com/events/message.im) あなたのアプリとユーザーのダイレクトメッセージをリッスン +- [`message.mpim`](https://api.slack.com/events/message.mpim) あなたのアプリが追加されているグループ DM をリッスン + +ボットが参加するすべての場所のメッセージをリッスンさせるには、これら 4 つのメッセージイベントをすべて選択します。ボットにリッスンさせるメッセージイベントの種類を選択したら、「**Save Changes**」ボタンをクリックします。 + +--- + +### メッセージをリッスンして応答する +アプリにロジックを組み込む準備が整いました。まずは `message()` メソッドを使用して、メッセージのリスナーをアタッチしましょう。 + +次の例では、アプリが参加するチャンネルとダイレクトメッセージに投稿されるすべてのメッセージをリッスンし、「hello」というメッセージに応答を返します。 + +```python +import os +from slack_bolt import App + +# ボットトークンと署名シークレットを使ってアプリを初期化します +app = App( + token=os.environ.get("SLACK_BOT_TOKEN"), + signing_secret=os.environ.get("SLACK_SIGNING_SECRET") +) + +# 'hello' を含むメッセージをリッスンします +# 指定可能なリスナーのメソッド引数の一覧は以下のモジュールドキュメントを参考にしてください： +# https://slack.dev/bolt-python/api-docs/slack_bolt/kwargs_injection/args.html +@app.message("hello") +def message_hello(message, say): + # イベントがトリガーされたチャンネルへ say() でメッセージを送信します + say(f"Hey there <@{message['user']}>!") + +# アプリを起動します +if __name__ == "__main__": + app.start(port=int(os.environ.get("PORT", 3000))) +``` + +アプリを再起動し、ボットユーザーが参加しているチャンネルまたはダイレクトメッセージに「hello」というメッセージを投稿すれば、アプリが応答するでしょう。 + +これはごく基本的なコード例ですが、最終的にやりたいことを実現するためにアプリをカスタマイズするための起点として利用できます。プレーンテキストを送信する代わりにボタンを表示するという、もう少しインタラクティブな動作を試してみましょう。 + +--- + +### アクションを送信して応答する + +インタラクティブ機能を有効にすると、ボタン、選択メニュー、日付ピッカー、モーダル、ショートカットなどの機能が利用できるようになります。イベントと同様に、Slack からのアクション（*ユーザーがボタンをクリックした*など）の送信先となる URL を設定する必要があります。 + +アプリ設定ページに戻り、左サイドメニューの「**Interactivity & Shortcuts**」をクリックします。別の **Request URL** ボックスを見つけます。 + +> 💡 デフォルトでは、Bolt はイベントに使用しているのと同じエンドポイントをインタラクティブコンポーネントにも使用するように設定されているため、上記と同じリクエスト URL（この例では「`https://8e8ec2d7.ngrok.io/slack/events`」）を使用します。このままの状態で、右下隅にある「**Save Changes**」ボタンを押してください。これでインタラクティブ機能がアプリで利用できるようになりました。 + +![Request URL の設定](../../assets/request-url-config.png "Request URL の設定") + +インタラクティブ機能が有効化されている時、ショートカット、モーダル、インタラクティブコンポーネント (ボタンや、選択メニュー、日付ピッカー) とのインタラクションはイベントとしてアプリに対して送信されます。 + +それでは、アプリのコードに戻り、これらのイベントを処理する為のロジックを追加しましょう。 +- まず、インタラクティブコンポーネントを含んだメッセージをアプリから送信します（このケースではボタン）。 +- 次に、ユーザーから返されるボタンクリックのアクションをリッスンし、それに応答します。 + +以下のコードの後の部分を編集し、文字列だけのメッセージの代わりに、ボタンを含んだメッセージを送信するようにしてみます。 + +```python +import os +from slack_bolt import App + +# ボットトークンと署名シークレットを使ってアプリを初期化します +app = App( + token=os.environ.get("SLACK_BOT_TOKEN"), + signing_secret=os.environ.get("SLACK_SIGNING_SECRET") +) + +# 'hello' を含むメッセージをリッスンします +@app.message("hello") +def message_hello(message, say): + # イベントがトリガーされたチャンネルへ say() でメッセージを送信します + say( + blocks=[ + { + "type": "section", + "text": {"type": "mrkdwn", "text": f"Hey there <@{message['user']}>!"}, + "accessory": { + "type": "button", + "text": {"type": "plain_text", "text":"Click Me"}, + "action_id": "button_click" + } + } + ], + text=f"Hey there <@{message['user']}>!" + ) + +# アプリを起動します +if __name__ == "__main__": + app.start(port=int(os.environ.get("PORT", 3000))) +``` + +`say()` の中の値を `blocks` という配列のオブジェクトに変えました。ブロックは Slack メッセージを構成するコンポーネントであり、テキストや画像、日付ピッカーなど、さまざまなタイプのブロックがあります。この例では `accessory` に `button` を持たせた「section」のブロックを、アプリからの応答に含めています。`blocks` を使用する場合、`text` は通知やアクセシビリティのためのフォールバックとなります。 + +ボタンを含む `accessory` オブジェクトでは、`action_id` を指定していることがわかります。これは、ボタンを一意に示す識別子として機能します。これを使って、アプリをどのアクションに応答させるかを指定できます。 + +> 💡 [Block Kit Builder](https://app.slack.com/block-kit-builder) を使用すると、インタラクティブなメッセージのプロトタイプを簡単に作成できます。自分自身やチームメンバーがメッセージのモックアップを作成し、生成される JSON をアプリに直接貼りつけることができます。 + +アプリを再起動し、アプリが参加しているチャンネルで「hello」と入力すると、ボタン付きのメッセージが表示されるようになりました。ただし、ボタンをクリックしても、*まだ*何も起こりません。 + +ハンドラーを追加して、ボタンがクリックされたときにフォローアップメッセージを送信するようにしてみましょう。 + +```python +import os +from slack_bolt import App + +# ボットトークンと署名シークレットを使ってアプリを初期化します +app = App( + token=os.environ.get("SLACK_BOT_TOKEN"), + signing_secret=os.environ.get("SLACK_SIGNING_SECRET") +) + +# 'hello' を含むメッセージをリッスンします +@app.message("hello") +def message_hello(message, say): + # イベントがトリガーされたチャンネルへ say() でメッセージを送信します + say( + blocks=[ + { + "type": "section", + "text": {"type": "mrkdwn", "text": f"Hey there <@{message['user']}>!"}, + "accessory": { + "type": "button", + "text": {"type": "plain_text", "text":"Click Me"}, + "action_id": "button_click" + } + } + ], + text=f"Hey there <@{message['user']}>!" + ) + +@app.action("button_click") +def action_button_click(body, ack, say): + # アクションを確認したことを即時で応答します + ack() + # チャンネルにメッセージを投稿します + say(f"<@{body['user']['id']}> clicked the button") + +# アプリを起動します +if __name__ == "__main__": + app.start(port=int(os.environ.get("PORT", 3000))) +``` + +`app.action()` を使って、先ほど命名した `button_click` という `action_id` をリッスンしています。アプリを再起動し、ボタンをクリックすると、アプリからの「clicked the button」というメッセージが新たに表示されるでしょう。 + +--- + +### 次のステップ +はじめての [Bolt for Python アプリ](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)をソケットモードを使って構築することができました。🎉 + +ここまでで基本的なアプリをセットアップして実行することはできたので、次は自分だけの Bolt アプリを作る方法を調べてみましょう。参考になりそうな記事をいくつかご紹介します。 + +* [基本的な概念](/bolt-python/concepts#basic)について読む。Bolt アプリがアクセスできるさまざまメソッドや機能について知ることができます。 +* [`events()` メソッド](/bolt-python/concepts#event-listening)でボットがリッスンできるイベントをほかにも試してみる。すべてのイベントの一覧は [API サイト](https://api.slack.com/events)で確認できます。 +* Bolt では、アプリにアタッチされたクライアントから [Web API メソッドを呼び出す](/bolt-python/concepts#web-api)ことができます。API サイトに [220 以上のメソッド](https://api.slack.com/methods)を一覧しています。 +* [API サイト](https://api.slack.com/docs/token-types)でほかのタイプのトークンを確認する。アプリで実行したいアクションによって、異なるトークンが必要になる場合があります。HTTPの代わりにソケットモードを利用したい場合には、`connections:write` のスコープを追加した、追加のトークン (`xapp`) が必要です。 From 217fba5588899d3077ff6a8d2f5e210a940062c9 Mon Sep 17 00:00:00 2001 From: hirosassa Date: Thu, 5 Aug 2021 15:07:23 +0900 Subject: [PATCH 2/2] Apply suggestions from code review @seratch Thanks for your review! Suggested changes are applied. Co-authored-by: Kazuhiro Sera --- docs/_tutorials/ja_getting_started.md | 30 +++++++++++----------- docs/_tutorials/ja_getting_started_http.md | 4 +-- 2 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/_tutorials/ja_getting_started.md b/docs/_tutorials/ja_getting_started.md index 3bc52993e..cd9b2eea0 100644 --- a/docs/_tutorials/ja_getting_started.md +++ b/docs/_tutorials/ja_getting_started.md @@ -17,7 +17,7 @@ redirect_from: この手順を全て終わらせたら、あなたはきっと ⚡️[Slack アプリのはじめ方](https://github.com/slackapi/bolt-python/tree/main/examples/getting_started)のサンプルアプリを動作させたり、それに変更を加えたり、自分のアプリを作ったりすることができるようになるでしょう。 -> 💡 このガイドでは、[Socket Mode](https://api.slack.com/apis/connections/socket) を利用します。Socket Modeを使い始めるオススメの方法は、あなたのチームの為に何かを作ることです。すでにあなたのアプリがHTTPの通信プロトコルを利用したいとわかっている場合には、このドキュメントと並列する [Getting Started over HTTP](/bolt-python/tutorial/getting-started-http) を参照してください。 +> 💡 このガイドでは[ソケットモード](https://api.slack.com/apis/connections/socket) を利用します。ソケットモードは、Slack アプリ開発をとりあえず始めてみるときやあなたのチームだけのためのアプリをつくるときにおすすめのやり方です。もしすでに HTTP をアプリのコミュニケーションプロトコルとしてするとわかっているなら、HTTP　の方式に対応した同様のドキュメントである [Bolt 入門ガイド（HTTP）](/bolt-python/tutorial/getting-started-http) を参照してください。 --- @@ -40,9 +40,9 @@ redirect_from: Slack アプリでは、[Slack API へのアクセスの管理に OAuth を使用します](https://api.slack.com/docs/oauth)。アプリがインストールされると、トークンが発行されます。アプリはそのトークンを使って API メソッドを呼び出すことができます。 Slack アプリで使用できるトークンには、ユーザートークン（`xoxp`）とボットトークン（`xoxb`）、アプリレベルトークン（`xapp`）の 3 種類があります。 -- [ユーザートークン](https://api.slack.com/authentication/token-types#user) を使用すると、ユーザーがアプリをインストールまたは認証した後、アプリがそのユーザーを代理して API メソッドを呼び出すことができます。1 つのワークスペースに複数のユーザートークンが存在する可能性があります。 +- [ユーザートークン](https://api.slack.com/authentication/token-types#user) を使用すると、アプリをインストールまたは認証したユーザーに成り代わって API メソッドを呼び出すことができます。1 つのワークスペースに複数のユーザートークンが存在する可能性があります。 - [ボットトークン](https://api.slack.com/authentication/token-types#bot) はボットユーザーに関連づけられ、1 つのワークスペースでは最初に誰かがそのアプリをインストールした際に一度だけ発行されます。どのユーザーがインストールを実行しても、アプリが使用するボットトークンは同じになります。_ほとんど_のアプリで使用されるのは、ボットトークンです。 -- [アプリレベルトークン](https://api.slack.com/authentication/token-types#app) は、組織に渡ってあなたのアプリを表すものです。所属する組織内の全てのワークスペースに、全ての個人ユーザによってインストールされたアプリについても同様です。アプリレベルトークンは、ウェブソケット通信を行うアプリを作る際に通常使われます。 +- [アプリレベルトークン](https://api.slack.com/authentication/token-types#app) は、全ての組織（とその配下のワークスペースでの個々のユーザーによるインストール）を横断して、あなたのアプリを代理するものです。アプリレベルトークンは、アプリの WebSocket コネクションを確立するためによく使われます。 このガイドではボットトークンとアプリレベルトークンを使用します。 @@ -56,7 +56,7 @@ Slack アプリで使用できるトークンには、ユーザートークン ![OAuth トークン](../../assets/bot-token.png "ボット用 OAuth トークン") -5. 次に「**Basic Informationのページ**」まで戻り、アプリトークンのセクションまで下にスクロールし「**Generate Token and Scopes**」をクリックしてアプリレベルトークンを作成します。このトークンに `connections:write` のスコープを付与し、作成された `xapp`トークンを保存します。これらのトークンはこのあと利用します。 +5. 次に「**Basic Informationのページ**」まで戻り、アプリトークンのセクションまで下にスクロールし「**Generate Token and Scopes**」をクリックしてアプリレベルトークンを作成します。このトークンに `connections:write` のスコープを付与し、作成された `xapp` トークンを保存します。これらのトークンは後ほど利用します。 6. 左サイドメニューの「**Socket Mode**」を有効にします。 @@ -92,15 +92,15 @@ Bolt for Python のパッケージを新しいプロジェクトにインスト 1. **OAuth & Permissions ページのボットトークン (xoxb) をコピー**して、新しい環境変数に保存します。以下のコマンド例は Linux と macOS で利用できます。[Windows でもこれに似たコマンドが利用できます](https://superuser.com/questions/212150/how-to-set-env-variable-in-windows-cmd-line/212153#212153)。 ```shell -export SLACK_BOT_TOKEN=xoxb- +export SLACK_BOT_TOKEN=xoxb-<ボットトークン> ``` 2. **OAuth & Permissions ページのアプリレベルトークン（xapp）をコピー**して、別の環境変数に保存します。 ```shell -export SLACK_APP_TOKEN= +export SLACK_APP_TOKEN=<アプリレベルトークン> ``` -> 🔒 全てのトークンは安全に保管してください。最低限、パブリックなバージョンコントロールにチェックインすることは避けてください。また、上記の例のように環境変数を介してアクセスするようにしてください。詳細な情報は [best practices for app security](https://api.slack.com/authentication/best-practices).のドキュメントを参照してください。 +> 🔒 全てのトークンは安全に保管してください。少なくともパブリックなバージョン管理にチェックインするようなことは避けるべきでしょう。また、上にあった例のように環境変数を介してアクセスするようにしてください。詳細な情報は [アプリのセキュリティのベストプラクティス](https://api.slack.com/authentication/best-practices)のドキュメントを参照してください。 完了したら、アプリを作ってみましょう。以下のコマンドを使って、仮想環境に Python の `slack_bolt` パッケージをインストールします。 @@ -124,7 +124,7 @@ if __name__ == "__main__": SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"]).start() ``` -このようにトークンがあれば、最初の Bolt アプリが作成できます。「`app.py`」ファイルを保存して、コマンドラインで以下を実行します。 +このようにトークンさえあれば、最初の Bolt アプリを作成することができます。「`app.py`」ファイルを保存して、コマンドラインで以下を実行します。 ```script python3 app.py @@ -139,9 +139,9 @@ python3 app.py Slack ワークスペースで発生するイベント（メッセージが投稿されたときや、メッセージに対するリアクションがつけられたときなど）をリッスンするには、[Events API を使って特定の種類のイベントをサブスクライブします](https://api.slack.com/events-api)。 -> 💡 このチュートリアルの序盤でソケットモードを有効にしました。ソケットモードを使うことで、アプリがパブリックなHTTPエンドポイントを公開せず、イベントAPIやインタラクティブコンポーネントを利用できるようになります。このことは、開発時やファイヤーウォールの裏からのリクエストを受ける際に便利です。HTTPはホスティングされた環境にデプロイされたアプリや、Slack App Directoryで配布されるアプリに向いています。これらの情報については、[このドキュメント](/bolt-python/tutorial/getting-started-http).を参照してください。 +> 💡 このチュートリアルの序盤でソケットモードを有効にしました。ソケットモードを使うことで、アプリが公開された HTTP エンドポイントを公開せずに Events API やインタラクティブコンポーネントを利用できるようになります。このことは、開発時やファイヤーウォールの裏からのリクエストを受ける際に便利です。HTTP での方式はホスティング環境にデプロイするアプリや Slack App Directoryで配布されるアプリに適しています。HTTP での情報については[このドキュメント](/bolt-python/tutorial/getting-started-http)を参照してください。 -それでは、Slackにどのイベントをリッスンするかを教えてあげましょう。 +それでは、私たちがどのイベントをリッスンしたいかを Slack に伝えましょう。 イベントが発生すると、そのイベントをトリガーしたユーザーやイベントが発生したチャンネルなど、イベントに関する情報が Slack からアプリに送信されます。アプリではこれらの情報を処理して、適切な応答を返します。 @@ -189,14 +189,14 @@ if __name__ == "__main__": ### アクションを送信して応答する -インタラクティブ機能を有効にすると、ボタン、選択メニュー、日付ピッカー、モーダル、ショートカットなどの機能が利用できるようになります。アプリ設定ページの「**Interactivity & Shortcuts**」を見てみましょう。 +インタラクティブ機能を有効にすると、ボタン、選択メニュー、日付ピッカー、モーダル、ショートカットなどの機能が利用できるようになります。アプリ設定ページの「**Interactivity & Shortcuts**」にアクセスしてください。 -> 💡 ソケッットモードを有効にしていると、デフォルトで、基本的なインタラクティブ機能が有効になっていることに気づくでしょう。追加のアクションは不要です。HTTPを使っている場合は、Slackに対して、イベントを送信する為のリクエストURLを設定する必要があります。 +> 💡 ソケットモードを有効にしているとき、デフォルトで基本的なインタラクティブ機能が有効になっていることに気づくでしょう。追加のアクションは不要です。もし HTTP を使っている場合、Slack からのイベント送信先である Request URL を設定する必要があります。 -インタラクティブ機能が有効化されている時、ショートカット、モーダル、インタラクティブコンポーネント (ボタンや、選択メニュー、日付ピッカー) とのインタラクションはイベントとしてアプリに対して送信されます。 +インタラクティビティが有効化されていれば、ショートカット、モーダル、インタラクティブコンポーネント (例：ボタン、選択メニュー、日付ピッカー) とのインタラクションはイベントとしてあなたのアプリに送信されます。 それでは、アプリのコードに戻り、これらのイベントを処理する為のロジックを追加しましょう。 -- まず、ボタンを含んだメッセージをアプリから送信します。 +- まず、インタラクティブコンポーネント（ここではボタン）を含んだメッセージをアプリから送信します。 - 次に、ユーザーから返されるボタンクリックのアクションをリッスンし、それに応答します。 以下のコードの後の部分を編集し、文字列だけのメッセージの代わりに、ボタンを含んだメッセージを送信するようにしてみます。 @@ -230,7 +230,7 @@ def message_hello(message, say): @app.action("button_click") def action_button_click(body, ack, say): - # Acknowledge the action + # アクションのリクエストを確認 ack() say(f"<@{body['user']['id']}> clicked the button") diff --git a/docs/_tutorials/ja_getting_started_http.md b/docs/_tutorials/ja_getting_started_http.md index 632776f68..8dd033f03 100644 --- a/docs/_tutorials/ja_getting_started_http.md +++ b/docs/_tutorials/ja_getting_started_http.md @@ -1,5 +1,5 @@ --- -title: Bolt 入門ガイド HTTP +title: Bolt 入門ガイド（HTTP） order: 5 slug: getting-started-http lang: ja-jp @@ -9,7 +9,7 @@ redirect_from: - /ja-jp/getting-started-http - /getting-started-http/ja-jp --- -# Bolt 入門ガイド HTTP +# Bolt 入門ガイド（HTTP）
このガイドでは、**HTTP上で Bolt for Python** を使った Slack アプリの設定と起動する方法について説明します。ここで説明する手順は、新しい Slack アプリを作成し、ローカルの開発環境をセットアップし、Slack ワークスペースからのメッセージをリッスンして応答するアプリを開発するという流れになります。