【LINE WORKS】LINE WORKS API 2.0をPostmanで手っ取り早く試してみる【サンプルあり】

# はじめに
4/1にLINE WORKS APIの新しいバージョン「API2.0」が正式リリースされ、従来のAPIから大幅な改善がされた。
アクセストークンの取得方式も変更され、以下の二種類が用意された。

- User Account認証
    - LINE WORKSユーザーでログインを行い、Access Tokenを発行してAPIを利用する方法。
    - スマホアプリやWebアプリ等に組み込む場合はこちらをつかう。
- Service Account認証
    - 仮想管理者アカウントを使用して認証を行い、Access Tokenを発行してAPIを利用する方法。
    - チャットボットやバッチ処理等でシステムがAPIを利用する場合はこちらを使う。

今回は、それぞれのアクセストークン取得を試すとともにいくつかのAPIの実行を、「Postman」で試してみる。

# 前提
- LINE WORKSテナントを作成済み、かつ、Developer Consoleの操作権限があること。
    - フリープラン以上 (有料プランである必要なし)
- Postmanがインストールされている環境であること。
    - 本記事では v9.19 を利用。

# サンプルファイル
今回、PostmanでLINE WORKS API 2.0を試すための、collectionとenvironmentのサンプルファイルを用意した。

https://github.com/mmclsntr/lw-api-2_0-postman-demo-sample 

これを使ってAPIを試してみる。

# Postman用サンプルの読み込み
Postmanの画面上の「Import」からサンプルファイルを取り込む。

![スクリーンショット 2022-05-10 19.49.09.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/e061c7f2-c76f-ec31-fd00-1dd609009ffb.png)

「Import」画面で、リポジトリ内にあるPostman用サンプルファイル２種 (CollectionとEnvironment) をインポートする。

- `postman/demo.postman_collection.json`
    - 認証周りとAPIリクエストの設定を含むCollectionファイル。
- `postman/demo.postman_environment.json`
    - 環境変数の設定を含むEnvironmentファイル。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/075522a0-d332-4703-b28f-b4f3e781d9d8.png)

インポートすると、Collectionsに `API 2.0 demo` と Environmentsに `demo@API2.0` が追加される。
これら2つを使ってAPIを試行する。

# アプリの作成
APIを使う前準備として、Developer Consoleでアプリを作成する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/12e5b3bf-2a8d-536e-1ea5-7a5b745f02fc.png)

「アプリの新規作成」からアプリを作成する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/dbb397dc-6efa-6fb5-4965-ffe048c36437.png)

アプリを作成すると、 `Client ID` と　`Client Secret` が生成される。
これらの秘匿情報をPostmanに設定する。

PostmanのEnvironment `demo@API2.0` を開く。
`CLIENT_ID` と `CLIENT_SECRET` にそれそれ値を入れて保存する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/c0a44340-718b-4cea-fd56-ef41133d80fa.png)

また、APIリクエスト時にEnvironmentを使うために、右上のプルダウンから該当のEnvironmentを事前に選択しておく。

![スクリーンショット 2022-05-10 23.40.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/698fef56-f341-d559-5f89-c5b2b954ded2.png)


# User Account 認証でAPIリクエスト
「User Account認証」とは、LINE WORKSユーザーでログインをすることで認証しアクセストークンを発行する方法。OAuth 2.0 に準拠した形となっている。

https://developers.worksmobile.com/jp/reference/authorization-auth?lang=ja 

## リダイレクトURLとScopeの設定
PostmanでUser Account認証を行うために、事前にいくつかDeveloper Consoleで追加の設定を行う。

まず、「リダイレクトURL」を登録する。
アクセストークン取得のフロー内で行うLINE WORKSユーザー認証 (ログイン) の後に、Postmanへリダイレクトさせる必要がある。

そのために、事前に以下のURLをLINE WORKSのアプリに登録しておく。

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

6/16 追記
※　ブラウザ版Postmanを使う場合はこちら。
`https://oauth.pstmn.io/v1/browser-callback`

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/5ecfadab-873f-1c00-2281-240b7f36948a.png)


次に、「OAuth Scopes」を設定する。これから発行するアクセストークンの権限範囲が設定される。

ユーザー取得のAPIを実行するため、 `user.read` のScopeを選択する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/d41873c7-9d93-2ec9-031d-458c7e6dbeec.png)

## アクセストークン取得
Postmanを使い、User Account認証でアクセストークンを取得する。

`API 2.0 demo` Collectionの「Authorization」タブから実行する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/cc89f019-610f-41a1-7d6c-c7284ebae583.png)

User Account認証は、前述した通り「OAuth 2.0」に準拠した認可方式となっている。PostmanはOAuth 2.0によるAPI認証に対応しており、LINE WORKS API 2.0のUser Account認証も利用できる。

今回のサンプルでは、既に必要な値が入っており、すぐにUser Account認証を実行できるようになっている。

念の為「Scope」の項目に、今回必要な `user.read` が入っていることを確認する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/c36f6277-d590-b976-7fd9-ba3c11cc0862.png)

「Get New Access Token」からアクセストークン取得を開始する。

はじめに、ブラウザが立ち上がり、LINE WORKSのログイン画面が表示される。ここに、認証をしたいユーザーのログイン情報をいれてログインを行う。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/17cbf37b-17d6-44b9-32fe-4ae0c9c0798e.png)

ログインが成功するとポップアップが表示され、表示に従って進めるとPostmanへ戻り、認証が成功した旨が表示される。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/f133fc8e-2ace-f775-6aff-1a20cde0e765.png)

その後、取得結果が表示される。ここで「Use Token」を押すことで、取得したアクセストークンを利用可能な状態となる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/9e6ff74c-7013-1096-9e30-f53e0a1099e0.png)

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/b9791690-08bd-8d4e-dd3e-a95022f5d86e.png)

これでUser Account認証を使ったアクセストークン取得は完了。

## API実行
取得したアクセストークンを使って、ユーザー取得のAPIリクエストを試してみる。

https://developers.worksmobile.com/jp/reference/user-get?lang=ja

サンプルの「Users ユーザーの取得」を利用する。「Authorization」には「Inherit auth from parent」が設定されており、上で取得したアクセストークンを使ったリクエストを実行できる状態となっている。

「Path Variables」を見ると `userId` には `me` が入っている。`me` は、認証をしたユーザー自身を指すエイリアスであり、これが指定されているため、そのユーザー自身のユーザー情報を取得するようになっている。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/7a969b4e-9ca5-28fc-bbc1-e674549ac03e.png)

「Send」から実行し、リクエストが成功するとResponseが下に表示される、

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/a27242ee-c67c-512d-3a15-9527fbe1cc1b.png)

上記で　`me` を指定したパスパラメータ `userID` には他にも、ユーザーID (上記レスポンス内に含まれる `userId`の値。UUID形式のリソースID) やログインID (メールアドレス形式のもの) 、ExternalKeyも指定できる。

ここまで、User Account認証によって取得したアクセストークンを使ったAPIリクエストの一例を示した。
次に、Service Account認証によるアクセストークンとAPIリクエストを記す。

----

# Service Account 認証でAPIリクエスト
「Service Account認証」は、アプリ専用の仮想管理者アカウント (Service Account) を使用して認証を行いアクセストークンを発行する方法。OAuth 2.0 を拡張した、JWTを利用した認可方式となっている。

https://developers.worksmobile.com/jp/reference/authorization-sa?lang=ja

## サービスアカウントとScopeの設定
PostmanでService Account認証を行うために、事前にDeveloper Consoleで追加の設定を行う。

LINE WORKSのアプリの設定画面を開き、まず、「Service Account」を発行する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/bdc3861c-bff0-42de-523b-904fe5b0d4f3.png)

発行すると、管理者権限が付与された仮想アカウントが作成される。

加えて、サービスアカウントの発行後に「Private Key」を発行できるようになる。これはアクセストークン取得時に必要な秘密鍵のため、発行 & ダウンロードをし、保管しておく。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/65f19c36-9b1f-c1b1-4f10-fe2852881f13.png)

次に、User Account認証の際と同じように「OAuth Scopes」を編集する。
今回は、ユーザー取得とBotからのメッセージ送信のAPIを実行するため、 `user.read` `bot` のScopeを選択する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/dee2f0cc-35f2-a1fc-b3d7-7f21ad2ac66c.png)

設定後、取得したサービスアカウント情報をPostmanに追加設定する。

Postmanの `demo@API2.0` Environmentを開く。
`SERVICE_ACCOUNT` と `PRIVATE_KEY` にそれそれ値を入れて保存する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/9b107ae0-fb86-58ba-3394-35490d478536.png)

## Botの用意
Botからのメッセージ送信のAPIを実行するために、Botを用意する。
※ 「API Interface」に「API 2.0」が選択されているBotが既に存在していればそちらを使ってもOK。

Developer Consoleから「Bot」を開く。

「登録」からBotを追加する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/b7802ea5-fad4-cc53-2c28-fbaa64f967eb.png)

必要な情報を入力し、保存する。この時、「API Interface」に「API 2.0」が選択されていることを確認する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/4dac9915-5ba4-d95a-8596-80dea28b0505.png)

作成すると `Bot ID` が発行される。メッセージ送信時に利用するため、どこかにメモしておく。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/2eb30cee-672b-4762-0ccc-fa4bc8bb53a9.png)

次にLINE WORKS管理画面でBotの追加作業を行う。
「サービス > Bot」からBotを追加する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/deeaf80d-54ce-5d9d-f9ec-bb8758bbf462.png)

追加後は、Bot詳細から公開設定を行い、テナント内のユーザーが使えるようにする。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/725b900e-4c88-caab-488d-429dc5813b3f.png)

これで、Botの準備は完了。

## アクセストークン取得
Postmanを使い、Service Account認証でアクセストークンを取得する。

`API 2.0 demo` Collectionの「Access Token 取得」のAPIを実行することで、アクセストークンの取得を行う。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/df73be17-b6f5-c477-8cc8-6867fce55fb8.png)

このサンプルでは「Pre-request Script」に、API実行の前処理としてJWTを生成するスクリプトを登録している。生成後にリクエストのBodyに乗せられ送られる。
また、Bodyのscopeに、今回必要な `user.read,bot` Scopeがセットされていることを確認する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/51aecbd6-3685-a2ae-865e-b8c1b49f013f.png)


「Send」から実行し、リクエストが成功するとResponseが下に表示される、

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/271d9f9e-a8ac-a91f-b04a-a9a809fc5237.png)

リクエストが成功すると、レスポンスの　`access_token` にアクセストークンが格納される。
また、このサンプルではこのアクセストークンの値を、変数 `{{access_token}}` に格納するよう設定されているため、実際のAPIを実行する際はこの変数を使ってAPI認証を設定する。

## API実行
Service Account認証で取得したアクセストークンを使って、User Account認証の際も実行したユーザー取得のAPIと、Botからのメッセージ送信のAPIを実行してみる。

### ユーザー取得APIの実行
先に述べた通り、サービスアカウントは仮想の管理者アカウントであるため、管理者による操作と同等の権限によるAPI呼び出しとなる。

先ほどのUser Account認証でも実行したユーザー取得APIを使って、ユーザー情報を取得する。

https://developers.worksmobile.com/jp/reference/user-get?lang=ja

同じくサンプルの「Users ユーザーの取得」を利用する。

先ほどは　`me` を指定していたが、今度は自身のログインID (Email) を `userId` パラメータに指定してリクエストしてみる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/ea8db280-ebab-d535-5512-7194d9ef1e8b.png)

また、「Authorization」で、取得したアクセストークンを使うよう設定する。
Typeを「Bearer Token」に切り替え「Token」に `{{access_token}}` を指定する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/952ba11f-27a9-1773-e658-d7cc8f40c7b5.png)

これで「Send」するとリクエストされ、レスポンスが表示される。

### Bot メッセージ送信APIの実行
次に、Botメッセージ送信APIを実行してみる。

https://developers.worksmobile.com/jp/reference/bot-user-message-send?lang=ja 

サンプルの「Bot メッセージの送信 - ユーザー指定」を利用する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/493077d0-177c-efbe-a26e-c7c73b3bb059.png)

「Path Variables」の `botId` には、作成したBotのBot IDを、`userId` には自身のログインID (Email) を指定する。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/ad20401a-053f-ee84-c35d-281c687f9610.png)

「Authorization」にはあらかじめBearer Tokenが使われるよう設定してある。
「Body」には、Botから「Hello」とテキストを送るための内容が入れられている。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/3653b03f-40e9-c988-8e09-38bd427c02cd.png)

これで「Send」をし、リクエストが成功すると、このように指定したユーザーに対してBotから「Hello」とメッセージが送られる。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/241369/4b327cf5-a1d4-c56d-c2a1-7a4faa42e885.png)

# まとめ
LINE WORKS API 2.0 を手っ取り早く実行するためのサンプルを用意し、使い方を説明した。
特に、OAuth 2.0 へ準拠されたことで認可周りをPostmanで簡単に組めるようになり、APIの検証が楽になった。

今回は2つのAPIを例としたが、他のAPIリクエストについてもサンプルのCollection配下に追加すれば、同様の手順で検証ができるため活用してもらえればと思う。