LINE WORKS API 2.0について

LWTT LINE WORKS API2.0正式リリース！変更点まるっと早わかり勉強会！
登壇資料
https://lwugdev.connpass.com/event/244399/

Transcript

1. LINE WORKS API 2.0について ワークスモバイルジャパン株式会社 ⼭﨑 慎太郎
2. 3 ⾃⼰紹介 ⼭﨑 慎太郎 Shintaro Yamasaki ワークスモバイルジャパン株式会社 Planning&Governance本部 役割 : PdM 担当 : API/Developer機能周り 拠点 : ⼤阪 2022/03 ⼊社 前職は AWS を中⼼とした設計・構築やバックエンド開発・チャットボット開発に従事していました。 特にサーバーレスが好き。メインは Python Twitter @mmclsntr Github @mmclsntr
3. 今⽇お話しすること 4 LINE WORKS API 2.0 の概要と、重要なポイントを紹介します。 お話ししないこと • 1つ1つの API に関する詳細仕様やコード例。 • その他 Developer 機能。 • Bot (API 2.0 に関係しないところ) • SSO • SAML App • LINE WORKSログイン • App Link • IPT • LINE WORKS アプリの話。 アジェンダ 1. LINE WORKS APIとは 2. API 1.0 と API 2.0 について 3. API 1.0 から API 2.0 への変更点 4. API 2.0 のデモ • API 2.0 の認証設定や挙動の紹介。 5. API 2.0 への移⾏のお願い • API 1.0 の提供終了予定⽇や留意事項など。 6. Q&A • コメント欄に質問ください。最後に回答したいと思います
4. 1. LINE WORKS APIとは 5
5. LINE WORKS API とは LINE WORKS 上のデータにアクセスし制御するための Web API この API を使うことで LINE WORKS と連携したアプリケーションやチャットボットを開 発することができます。 API は無償で提供しています。※ ただし、プランによって利⽤できるAPIは異なります。 LINE WORKS API App 6
6. APIの活⽤事例 https://line.worksmobile.com/jp/cases/ [業務⾃動化・Bot] [連携ツール] を選択 7 導⼊事例ページを参照ください
7. 2. API 1.0 と API 2.0 について 8
8. API 1.0 と API 2.0 現在、LINE WORKS API には 2 バージョン存在しています。 n API 1.0 n 従来の LINE WORKS API。現在 ⾮推奨。 n 引き続き提供中だが、提供終了を予定。 n 今後、新機能や仕様変更への追従は⾏わない。 n API 2.0 n 従来のAPI (API 1.0) からリニューアル。 n 今後はこちらの API をお使いください。 n 2021年末から beta 版が提供され、2022/04に正式リリースとなった新しい API。 9
9. API 1.0 の提供終了予定について ※ API 1.0 と API 2.0 は、相互に互換性はありません。 • API認証周りから刷新されています。同じアクセストークンを使うことはできません。 API 1.0 提供終了予定⽇ 2023/04/30 API 2.0 への移⾏をお願いします。 10 お知らせ https://jp1-notice.worksmobile.com/view/#/detail-view/571?usess=1&serviceType=12&serviceLanguage=ja_JP
10. 3. API 1.0 から API 2.0 への変更点 11
11. API リニューアルの背景 API 1.0 の課題 • ニーズに合わせて建て増しで改修されていたために、拡張性や汎⽤性が低下 • 独⾃仕様が多くあり、開発者の負担の増加 API 2.0 の⽬的 • 利⽤しやすく、シンプルで、安定した API に改善。 12
12. API 1.0 から API 2.0 への主な変更点 1. サービス API / サーバー API の区分の撤廃 2. API 構造/形式の単純化 3. アクセストークン取得プロセスの刷新 4. リソース ID の提供 5. Pagination の実装 6. Rate limit の実装 7. フリープランで利⽤できる API の拡充 8. トークBotの callback event 形式・改ざんチェック⽅法の変更。 9. 組織連携 API 利⽤のための使⽤設定 ON/OFF が不要に。 10. その他、各所の⽤語・フィールド名の統⼀ 等 13
13. 変更点 1. サービス API / サーバー API の区分の撤廃 14 API が⽤途によって2種類に分類されていました。 API 1.0 • どちらに区分されているか1つ1つ意識する必要があり、使い勝⼿に影響していました。 • また、API 全体の複雑さにも起因していました。 サービス API サーバー API Drive メール カレンダー アドレス帳 メール カレンダー トークBot 組織連携 掲⽰板 Webアプリ等に組み込んで ユーザーが利⽤する。 チャットボットやバッチ処理等で システムが利⽤する。
14. 変更点 1. サービス API / サーバー API の区分の撤廃 15 API 2.0 サービス API / サーバー API の区分を撤廃し1つにまとめ、各APIがどちらに区分されているの か意識する必要がなくなりました。 また、アクセストークンの取得プロセスについても、改めて再定義しました (詳細は後述) アドレス帳 メール カレンダー トークBot 組織連携 掲⽰板 Drive API
15. 変更点 2. API 構造/形式の単純化 • 全体的に構造が複雑であり、予測可能でない形となっていました。 • カテゴリごとに形式がバラバラ • 類似 API の重複 • コンテンツのアップロード・ダウンロードの⽅式がバラバラ • など 16 API 1.0 API 2.0 • これらの問題を解消するよう、API 全体の構造や形式を整理しました。 API の構造や形式に関する改善点について、いくつか例を出して説明します。
16. 変更点 2. API 構造/形式の単純化 17 API 1.0 サーバーAPI トークBot メッセージ送信 apis.worksmobile.com/r/{API ID}/message/v1/bot/{botNo}/message/push サーバーAPI 組織連携 組織照会 apis.worksmobile.com/r/{API ID}/organization/v2/domains/{domainId}/orgunits/{externalKey} サービス API Drive ファイルのプロパティの閲覧 apis.worksmobile.com/r/{API ID}/drive/rl/{resourceLocation}/v2/files/{resourceKey} サービス API Drive 共有情報の閲覧 apis.worksmobile.com/{API ID}/drive/getShareInfo/v1 例. カテゴリごとに形式がバラバラ (1) Bot メッセージ送信 www.worksapis.com/v1.0/bots/{botId}/users/{userId}/messages Orgunit 組織の取得 www.worksapis.com/v1.0/orgunits/{orgUnitId} Drive マイドライブ - ファイルプロパティの取得 www.worksapis.com/v1.0/users/{userId}/drive/files/{fileId} Sharedrive 共有ドライブ - 共有ドライブアクセス権限リストの取得 www.worksapis.com/v1.0/sharedrives/{sharedriveId}/permissions API 2.0 バージョン指定パスの位置がそれぞれ異なる。 「www.worksapis.com/version/resources」に統⼀ {API ID} も指定不要。 ※ API ID⾃体を廃⽌。
17. 変更点 2. API 構造/形式の単純化 18 サーバー API 組織連携 グループ照会 apis.worksmobile.com/r/{API ID}/organization/v3/domains/{domainId}/groups/{externalKey} サービス API Drive グループフォルダ情報の閲覧 apis.worksmobile.com/{API ID}/drive/getGroupInfo/v1?groupId={groupId} サービス API Drive グループフォルダのファイルリストの取得 apis.worksmobile.com/{API ID}/drive/getGroupFileList/v1?resourceKey={resourceKey} Group グループの取得 www.worksapis.com/v1.0/groups/{groupId} Group チーム/グループ - チーム/グループフォルダプロパティの取得 www.worksapis.com/v1.0/groups/{groupId}/folder Group チーム/グループ - ファイルリストの取得 www.worksapis.com/v1.0/groups/{groupId}/folder/files/{fileId}/children 例. カテゴリごとに形式がバラバラ (2) API 1.0 API 2.0 グループ関連のAPIが、カテゴリそれぞれで 独⾃の形式となっている。 Group カテゴリに統合。形式も統⼀。
18. 変更点 2. API 構造/形式の単純化 補⾜. APIのカテゴリ分類も再構成されています。 19 ├── Bot │ └──トークBotの管理, メッセージ送信/受信 ├── Calendar │ └── カレンダーの管理 ├── Mail │ └── メールの管理 ├── Contact │ └── 連絡先情報 ├── Directory │ └──役職/階級情報, 利⽤権限タイプ, カスタムフィールド ├── Orgunit │ └── 組織情報 ├── User │ ├── ユーザー情報 │ └── LINE/LINE WORKS連携権限 ├── Group │ ├── グループ情報 │ └── チーム/グループフォルダの管理 ├── Drive │ └── マイドライブの管理 ├── Sharedrive │ └── 共有ドライブの管理 ├── Board │ └── 掲⽰板/投稿の管理 └── Audit └── 監査データのダウンロード ├── トークBot │ └──トークBotの管理, メッセージ送信/受信 ├── カレンダー │ └── カレンダーの管理 (サービスAPI/サーバーAPI別) ├── メール │ └── メールの管理 ├── アドレス帳 │ ├── 連絡先情報 │ └── LINE/LINE WORKS連携権限 ├── 組織連携 │ ├── 役職/階級情報, 利⽤権限タイプ, カスタムフィールド │ ├── 組織情報 │ ├── メンバー情報 │ └── グループ情報 ├── Drive │ ├── マイドライブの管理 │ ├── チーム/グループフォルダの管理 │ └── 共有ドライブの管理 ├── 掲⽰板 │ └── 掲⽰板/投稿の管理 └── 監査 └── 監査データのダウンロード API 2.0 API 1.0
19. 変更点 2. API 構造/形式の単純化 20 サービス API Drive ユーザー情報閲覧 apis.worksmobile.com/{API ID}/drive/getUserInfo/v1 サーバー API アドレス帳 アカウント情報の照会 apis.worksmobile.com/r/{API_ID}/contact/v2/accounts/{accountId} サーバー API 組織連携 メンバーの照会 apis.worksmobile.com/r/{API ID}/organization/v2/domains/{domainId}/users/{externalKey} サービスAPI カレンダー カレンダー作成 apis.worksmobile.com/r/{API_ID}/calendar/v2/users/me/calendarList サーバーAPI カレンダー カレンダー作成 apis.worksmobile.com/r/{API_ID}/calendar/v1/{accountId}/calendarList Calendar カレンダーの登録 www.worksapis.com/v1.0/calendars User ユーザーの取得 www.worksapis.com/v1.0/users/{userId} API 1.0 API 2.0 例. 類似APIの重複 {userId} には、ユーザーID, ログインID (email), External Key, me を指定可能。 ユーザー取得 カレンダー作成 ユーザー取得 カレンダー作成 対象のリソースやURLパスの内容が不揃い 重複しないよう整理。 似通ったAPIが複数存在。
20. 変更点 2. API 構造/形式の単純化 21 API 1.0 例. コンテンツのアップロード・ダウンロードの⽅式がバラバラ URLやリクエストボディ/ヘッダー、 ファイルデータの指定⽅法等がそれぞれ異なっていた。 API 2.0 形式やフローを統⼀ アップロードのフローについて
21. 変更点 3. アクセストークン取得プロセスの刷新 22 サービスAPI/サーバーAPIの撤廃に伴い、認証周りも刷新されました。 LINE WORKS API LINE WORKS サービスAPI Client App アクセストークン サービスAPI認証 アクセストークン取得 APIリクエスト LINE WORKS サーバーAPI アクセストークン APIリクエスト サーバーAPI認証 アクセストークン取得 API 1.0 アクセストークン取得 User Account Service Account アクセストークン取得 APIリクエスト アクセストークン 権限委任 アクセストークン 権限委任 API 2.0 User Account 認証 Service Account 認証 Client App サービスAPI/サーバーAPIそれぞれで認証が分かれており 使い分けが必要 - サービスAPI/サーバーAPIは撤廃され、APIは共通化。 - 認証⽅法も再設計し、 User Account認証 / Service Account認証 の2種類のアクセストークン取得⽅法を⽤意。 アドレス帳 メール カレンダー トークBot 組織連携 掲⽰板 Drive メール カレンダー
22. 変更点 3. アクセストークン取得プロセスの刷新 23 API 2.0 アクセストークンの取得には「User Account 認証」「Service Account 認証」の 2 種類存在します。 それぞれアクセストークン取得プロセスに特徴があるため、⽤途にあった認証⽅式を利⽤してください。 User Account 認証 Service Account 認証 概要 LINE WORKS ユーザー (User Account) で認証を⾏い、アクセ ストークンを発⾏。 API 1.0 におけるサービス API のAPI認証に相当 アプリ専⽤の仮想管理者アカウント (Service Account) で認証 を⾏い、アクセストークンを発⾏。 API 1.0 におけるサーバー API のAPI認証に相当。 認可⽅式 OAuth 2.0 (Authorization Code Grant) に準拠。 → さまざまなツールとの連携が容易に。 OAuth 2.0 の拡張した JWT ベースの認証⽅法。 付与される権限 認証を⾏ったユーザーの権限の⼀部をアクセストークンに⼀時委 任する。その権限範囲はOAuth Scopeで制御される。 管理者権限の⼀部をアクセストークンに⼀時委任する。その権限 範囲はOAuth Scopeで制御される。 流れ LINE WORKSユーザーでログインを⾏い、アクセストークンを発 ⾏。 Service Account の情報を使⽤して JWT ⽣成し、それをもとに アクセストークンを発⾏。 ⽤途 スマホアプリやWebアプリ上にAPI連携を組み込む場合。 チャットボットやバッチ処理等でシステムがAPIを利⽤する場合。
23. 変更点 3. アクセストークン取得プロセスの刷新 24 User Account 認証 Service Account 認証 ⼤まかなフローは API 1.0 と変わりません。 ⼤枠は API 1.0 を踏襲した形です。 API 1.0 におけるサービス API のAPI認証に相当 API 1.0 におけるサーバー API のAPI認証に相当 API 2.0
24. 変更点 3. アクセストークン取得プロセスの刷新 25 1.アクセストークンの⾃動延⻑機能の廃⽌。 • リフレッシュトークンを⽤いて再発⾏を⾏う形に統⼀しました。 2.「アプリ」の導⼊。 • API利⽤のための認証情報・権限の管理はこのアプリで⾏います。 • アプリは、⽤途に分けて複数作成することができます。 3.各認証情報をOAuth2.0ベースの名称に変更。 • Client ID, Client Secret, Scope, etc その他 API 認証周りの変更事項
25. その他変更点については 26 Developers Document にも API 間の違いに関するドキュメントがあります。 今回説明できなかった細かい変更点についても説明されています。 https://developers.worksmobile.com/jp/reference/difference-between-api?lang=ja
26. 変更されていないこと 27 1. SSO 2. SAML Apps 3. LINE WORKSログイン 4. IPT 5. App Link 6. トークBotの登録プロセス これらは API 1.0 / API 2.0 の項⽬ではなく、今回の API アップデートでも変更対象外です。
27. 4. API 2.0 のデモ 28
28. Postman で API 試⾏ LINE WORKS API 2.0 を「Postman」を使って試してみます。 29 皆さんの⼿元でも試すことができるよう、Postmanのテンプレートを公開しています。 デモ⽤サンプル https://github.com/mmclsntr/lw-api-2_0-postman-demo-sample 使い⽅記事 https://qiita.com/mmclsntr/items/eee8d8f3546410fe6652 ※ 私個⼈で作成して公開したものです。不具合等あれば上記GithubやQiita上で私宛に連絡ください。
29. その他 実装例 • Bubble.ioでの実装例 • https://qiita.com/mmclsntr/items/a9654a6480cb82f6f06b • PythonでのService Account認証実装例 • https://qiita.com/mmclsntr/items/0c118f40ffe7f36cd4eb 30 ※ 私個⼈で作成して公開したものです。不具合等あれば上記GithubやQiita上で私宛に連絡ください。
30. 5. API 2.0 への移⾏のお願い 31
31. API 1.0 の提供終了予定について ※ API 1.0 と API 2.0 は、相互に互換性はありません。 • API認証周りから刷新されています。同じアクセストークンを使うことはできません。 API 1.0 提供終了予定⽇ 2023/04/30 API 2.0 への移⾏をお願いします。 32 お知らせ https://jp1-notice.worksmobile.com/view/#/detail-view/571?usess=1&serviceType=12&serviceLanguage=ja_JP
32. Developers Documents 33 APIリファレンスは「LINE WORKS Developers」のドキュメントにあります。 https://developers.worksmobile.com/jp/?lang=ja
33. Developers Community 34 API について疑問点などありましたら、コミュニティもぜひご活⽤ください。 https://forum.worksmobile.com/jp/