はじめに
初めてLINE WORKS APIを使う人のために、API実行に必要な各種準備と流れについてまとめます。
特に、普段 LINE WORKS に馴染みのない方 向けに、LINE WORKSテナントの開設から整理します。
ポイント
- LINE WORKSテナントは無料で開設できる (フリープラン)
- APIは、フリープラン含め、すべてのプランで無料で利用可能。
- アクセストークンは、クライアント認証情報をもとに各自で発行する。
- アクセストークン発行のためのクライアント認証情報や設定は、Developer Console内で管理される「アプリ」で設定する。
LINE WORKS とは
「LINE WORKS」は、「ビジネス版LINE」とも呼ばれ、LINEのような使い勝手で利用できる、業務コミュニケーションのためのツールです。
チャット機能である「トーク」を基本に、その他にもカレンダーや掲示板、アドレス帳等の機能も備わったグループウェアとして提供されています。
LINE WORKS API とは
「LINE WORKS」との連携アプリを開発するためのWeb APIです。REST APIとして提供されています。
ドキュメントはこちら https://developers.worksmobile.com/jp/docs/api
チャットボットの開発はもちろん、組織やグループの管理、ファイルのアップロード/ダウンロードなど、LINE WORKSの様々な機能やリソースをAPIを通して無料で利用可能です。
APIでできること
例えば、以下のことをAPIを通して実現できます。
- チャットボット
- テキストやスタンプ、画像・ファイルのやりとり
- ボタンを含んだメッセージ (Flex Template)。
- リッチメニュー
- 掲示板への自動投稿
- カレンダーへ予定を自動追加
- 外部システムとのユーザー情報連携
[事前知識] アクセストークン発行とAPIリクエストの仕様について
まず、事前知識として、LINE WORKS APIのリクエスト方法と、それに必要なアクセストークンの、発行の仕組みについて整理します。
アクセストークンの発行について
LINE WORKS APIのアクセストークンの発行プロセスは、 OAuth 2.0 に準拠しています。
API実行の一連の流れは以下の通り。
- まずは、認可サーバーに認可リクエストを送り、アクセストークンを発行する。
- (1) 認可リクエスト
- (2) アクセストークン取得
- 取得したアクセストークンを用いて、APIサーバーへAPIリクエストを送る。
- (3) HTTPリクエスト w/ アクセストークン
- (4) レスポンス
APIの呼び出し方の詳細はドキュメント参考ください。
https://developers.worksmobile.com/jp/docs/api-call
アクセストークン取得に必要な「認可リクエスト」には、以下の2種類の方法が用意されています。
| Service Account認証 | User Account認証 | |
|---|---|---|
| 概要 | 仮想管理者アカウント (Service Account) で認証を行い、アクセストークンを発行する。 | メンバーが認証を行い、アクセストークンを発行する。 |
| 認可方式 | OAuth 2.0 を拡張したJWTベースの方式。 | OAuth 2.0 (Authorization Code Grant) に準拠。 |
| 付与される権限 | 管理者権限の一部をアクセストークンに一時委任する。権限範囲はOAuth Scopeで制御される。 | 認証を行ったメンバーの権限の一部をアクセストークンに一時委任する。権限範囲はOAuth Scopeで制御される。 |
| フロー | Service Accountの情報からJWTを生成し、認可リクエストする。 | ログイン画面が表示され、メンバーのログイン情報 (ID/パスワード) でログインすることで、認可リクエストする。 |
| 用途 | チャットボットやバッチ処理など、システムがAPIを利用する場合。 | スマホアプリやWebアプリ上にAPI連携を組み込む場合。 |
Botアプリケーションを開発するシーンが多いと想定し、ここからは 「Service Account認証」 を使う前提とします。
クライアント認証情報の管理や設定
この認可リクエストに必要なクライアント認証情報やOAuthの設定は 「アプリ」 というDeveloper機能で管理します。
アプリでは、以下の情報についてが管理されます、
- OAuthのクライアント認証情報と設定
- Client ID
- Client Secret
- Redirect URL (User Account認証のみ)
-
OAuth Scope
- 権限範囲の設定
- Service Accountの設定
- Service Account (Service Account認証のみ)
-
Private Key (Service Account認証のみ)
- Service Accountの秘密鍵、
開発者は、これらの情報を取得し アクセストークン発行の仕組みを各自で実装する 必要があります。
ここからは、その設定の取得に必要な前準備として、LINE WORKS テナントの開設から説明します。
LINE WORKS API を使うために必要なもの
以下が必要です。
-
LINE WORKS テナント
- 当然ながらLINE WORKS自体が必要。
- LINE WORKS テナントの中に様々なサービスが含まれている。
- トーク, 掲示板, カレンダー, アドレス帳, ...
- それらのサービスを、APIを通して利用することができる。
-
アクセストークン取得のための情報 (アプリ)
- APIリクエストにはアクセストークンが必要。そのアクセストークンは自分で発行する。
- そのための情報を管理する「アプリ」を作成する必要がある。
-
アクセストークン取得とAPIリクエストのための実行環境
- 任意の言語でアプリケーションを作成する、または、検証としてPostman等のツールを用意する。
ここでは、LINE WORKS テナントとアプリの作成について説明します。
準備の流れ
1. LINE WORKS テナントの開設
※ 既に作成済みの場合はスキップ
まずは、LINE WORKSテナントを開設する。
LINE WORKSには「フリー」プランがあり、無料で開設できます。
https://line.worksmobile.com/jp/pricing/
LINE WORKS API はそのフリープランでも利用できます。
今回はフリープランを前提として手順をまとめます。
フリープランのテナントを開設
まず、以下のリンクから開設を始めます。
画面に沿って必要情報を入力していきます。
この開設準備で、初回メンバーの作成も一緒に行えます。この初回メンバーは最高管理者として、全体の管理設定を行うことができます。
「電話番号」を用いることもできますが、今回は汎用性が高い「メールアドレス」で設定します。
この画面で、「別の方法で新規開設」を選択。
ID (ユーザーごとに一意のID) とグループ名 (グループを示す一意のID) 、パスワードを入力し、管理者アカウントを作成。
次にメールアドレスで認証する。メールアドレスを入力し、認証番号を取得。
送られてきた認証番号を入力。
認証が成功すると登録完了です。
他にメンバーを追加する場合は、この画面から招待できるが、後で管理画面から追加することも可能 (後述します)。
下の「サービスをはじめる」から、LINE WORKSを開きます。
初回は同意画面が出るため、確認および同意を行い、利用開始となります。
これでテナントの開設は完了です。
2. 共同開発者の作成
※既に設定済み、または、複数人で共同開発をしない場合はスキップ
LINE WORKS APIを含むDeveloper機能の設定は「Developer Console」で行います。
テナント開設時に作成した初回メンバーは、テナントの「最高管理者」の権限を持っており、その権限にはDeveloper Consoleへのアクセス権限も含まれています。
もし、追加で他の開発者メンバーも入れたい場合は、新たにメンバーを追加し、加えて、Developer Consoleへのアクセス権限を与える必要があります (通常メンバーはアクセス不可)。
ここからはその手順についてです。
管理画面へ移動 & テナントの初期設定
まずは、管理画面に移動。
管理画面は右上のアカウントメニューから移動できます。
または、以下リンクから開けます (要ログイン)
もし、管理者画面へのアクセスが初回の場合は「初期設定」が必要です。
「はい、設定します。」から画面に沿って再度テナントの情報についてチェックします。
必要のない内容については「スキップ」をしながら初期設定を完了させます。
完了したら右上の「×」で閉じます。
メンバーの追加
共同開発者用のメンバーを追加します。
左メニューの「メンバー > メンバー」からメンバー設定画面を開く。
画面右上の「メンバーの追加」から、メンバーを追加。
表示されたメンバー追加モーダル上に、メンバー情報を入力。
パスワードの作成方法は3択あるが、ここでは「自動作成」して渡す方法にします。
これを繰り返し、共同開発者の人数分のメンバーを追加。
ログイン情報を受け取ったメンバーは以下のURLからログイン (初回は要パスワード変更)。
Developer Consoleへのアクセス権限を設定
追加したメンバーに、Developer Consoleへのアクセス権限を与えます。
管理画面の左メニューの「セキュリティ > 管理者権限」から権限設定を行うことができます。
権限は4種類。
※ フリープランでは新たな権限の作成は不可
「最高管理者」は、テナント開設時に作成した初回メンバーに付与されている。割り当てられるのは1名のみ (別メンバーへの委任は可能)。
「副管理者」「IT管理者」「人事管理者」のうち、Developer Consoleへのアクセス権限を含むのは 「副管理者」 のみ。
今回は、先ほど追加したメンバーを「副管理者」に登録します。
「副管理者」の「管理者」タブを開き、右上の「管理者の追加」からメンバーを追加。
これで、共同開発者の設定は完了です。
3. Developer Consoleでアプリを作成
ここからは、APIを利用するための各種設定についてです。
まず、前述した通り、クライアント認証情報等を管理するための「アプリ」を作成します。
アプリを作成し、以下の情報を取得します。
- Client ID
- Client Secret
- Service Account
- Private Key
また、アクセストークンに委任する権限範囲 (OAuth Scopes) も併せて設定します。
※ Redirect URLはService Account認証では不要。
このアプリの作成や設定は、Developer Console上にて行います。
Developer Consoleへ移動
以下リンクから Developer Console へアクセス (要ログイン)
または、LINE WORKS Developersページ 右上の「Developer Console」からもアクセスできます。
初回アクセス時は「LINE WORKS APIサービス利用規約」への同意が求められます。
確認および同意すると、Developer Consoleにアクセスできます。
以下のような、「API」の画面でアプリを作成・編集・削除を行います。
アプリの作成
「アプリの新規追加」から、アプリを作成。
「同意して利用する」を押すとアプリが追加され、「アプリ情報」画面が表示されます。
この時点で、OAuthのクライアント認証情報である Client ID と Client Secret が生成されます。
追加で「アプリの説明」に説明文を入力し保存。
保存すると、アプリの画面が表示されます。
「API」画面に戻るとこのようにアプリリストに追加されています。
これでアプリの作成は完了です。
Service Accountを発行
アプリの画面から、以下のService Account情報を発行します。
- Service Account
- Private Key
- Service Accountの秘密鍵。
このService Accountは 仮想管理者アカウント として発行され、メンバー (User Account) における 最高管理者 と同等の権限を持つアカウントとして扱われます (最高管理者 = テナント開設時に作成した初回メンバー)。
Service Account認証においては、そのService AccountのユーザーIDと、それに対応するPrivate Keyを用いて、認可リクエストを送ることでアクセストークンを発行できます。
※ ただし、アクセストークンに委任される権限は、Service Account自体の権限すべて(最高管理者権限)ではなく、OAuth Scopesによって制限された権限範囲となります。権限範囲はこの後に設定します。
まず、アプリ画面のService Account項目にある「発行」からService Accountを発行します。
表示されるアラートメッセージを「OK」すると発行完了です。
発行すると、管理者に対してサービス通知が飛びます。
次に、Private Keyを発行します。
Private Key項目の「発行/再発行」から発行すると、keyファイルがダウンロードされます。
このファイルは別途、任意の場所で管理しておきます。
※ このPrivate Keyは、同じものを再発行することはできません。再び発行するとそれまでのPrivate Keyは無効となり新たなPrivate Keyが発行されます。
これでService Account情報の設定は完了です。
権限範囲 (OAuth Scopes) の設定
「OAuth Scopes」から、アクセストークンに委任する権限の範囲を設定します。
「OAuth Scopes」項目の「管理」を選択してScope一覧を表示します。
画像のように、「Bot」のAPI (読み出し・書き込み) を利用したい場合は bot にチェックをして保存します。
必要なScopeはAPIごとに定義されています。各APIリファレンスを参照ください。
例. ユーザーの取得
※ APIリファレンスに複数Scopeが記載されている場合は それらのうちの1つでも含まれていれば良いです (OR条件)
もしuser,user.read,directory,directory.readが記載されていれば、例えばuser.readのみが指定されていればAPIは実行できます。
これで、LINE WORKS APIを実行する準備は完了です。
アクセストークンの発行 & APIを実行
ここからは、前述した通り、作成したApp内の情報を使ってアクセストークンを発行 & API実行するための環境を用意する必要があります。
実行環境の例として、Postmanで実行するパターンが以下記事にまとめられています。まずはこれでAPIの挙動などを確認することを推奨します。
また、コマンドラインツールも個人で作成しました。これを使えばターミナル上で簡単にアクセストークンを発行できます。ぜひご活用ください。
(任意) チャットボットの作成
※チャットボットを作成しない場合はスキップ
トークルーム上で動くチャットボットを開発したい場合は、「Bot」を作成します。
LINE WORKSにおけるチャットボットの仕組みは以下のイメージです。
参照: https://developers.worksmobile.com/jp/docs/bot#how-bot-works
開発者は、LINE WORKS側のサーバーから送信されるCallback Event (送信されたメッセージ) を受け取る「Bot Servers」を用意します。
また、リプライは メッセージ送信 のAPIで行います。このAPIはリプライだけでなくチャットボットからのPush通知でも使用します。
Botの管理もDeveloper Console上で行います。
ここからはBotの作成手順です。
まず、Developer Consoleの左メニューの「Bot」からBotリスト画面を開きます。
右上の「登録」からBotを登録します。
表示される登録画面で、各種情報を入力して保存します。
各項目についてはドキュメントを参照ください。
「Callback URL」には、自前で用意したチャットボットアプリサーバーのURLを指定します。
Callbackの仕様については以下のドキュメントを参照ください。
Botの登録後、テナントで利用するためには管理画面で追加作業を行う必要があります。
「管理者画面」へ移動。「サービス > Bot」を開く。
右上の「Bot追加」からテナントへBotを追加。
追加するとBot一覧に表示されます。
加えて、Botを選択し、「修正」から、Botが使うことができるメンバーや公開設定を行います。
ここでは、「使用権限」を「すべて」にして全員が使用可能とし、「公開設定」をONにして連絡先から利用可能とします。
参考: https://guide.worksmobile.com/jp/admin/admin-guide/manage-service/bot/
これでBotの設定は完了です。
あとはチャットボットアプリを実装し、実現したいチャットボットを作り込んでいきます。
Botの実装の仕方については以下も参考ください (Python例)。
APIに関する注意事項
- APIごとに Rate Limit が設けられています。制限値を超えないように制御してください。
- アクセストークンの有効期限は 24時間 です。有効期限に合わせて定期的に更新してください。
その他、LINE WORKS APIについての情報が、Qiita上にも挙げられているため参考ください。
まとめ
LINE WORKS APIを利用するための準備として、LINE WORKSテナントの開設からまとめました。
API実行のために、まずはアクセストークンの発行が必要となるという点が特に重要です。
これでLINE WORKS APIを活用したアプリ開発を進めてください。
もし説明間違いや追記が必要な点がある場合はコメントお願いします！