LINE WORKS API 2.0について

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

Transcript

1. LINE WORKS API 2.0について
   ワークスモバイルジャパン株式会社
   ⼭﨑 慎太郎
   

   View Slide

2. 3
   ⾃⼰紹介
   ⼭﨑 慎太郎
   Shintaro Yamasaki
   ワークスモバイルジャパン株式会社 Planning&Governance本部
   役割 : PdM
   担当 : API/Developer機能周り
   拠点 : ⼤阪
   2022/03 ⼊社
   前職は AWS を中⼼とした設計・構築やバックエンド開発・チャットボット開発に従事していました。
   特にサーバーレスが好き。メインは Python
   Twitter @mmclsntr
   Github @mmclsntr
   

   View Slide

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
   • コメント欄に質問ください。最後に回答したいと思います
   

   View Slide

4. 1. LINE WORKS APIとは
   5
   

   View Slide

5. LINE WORKS API とは
   LINE WORKS 上のデータにアクセスし制御するための Web API
   この API を使うことで LINE WORKS と連携したアプリケーションやチャットボットを開
   発することができます。
   API は無償で提供しています。※ ただし、プランによって利⽤できるAPIは異なります。
   LINE WORKS API
   App
   6
   

   View Slide

6. APIの活⽤事例
   https://line.worksmobile.com/jp/cases/
   [業務⾃動化・Bot] [連携ツール] を選択
   7
   導⼊事例ページを参照ください
   

   View Slide

7. 2. API 1.0 と API 2.0 について
   8
   

   View Slide

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
   

   View Slide

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
   

   View Slide

10. 3. API 1.0 から API 2.0 への変更点
    11
    

    View Slide

11. API リニューアルの背景
    API 1.0 の課題
    • ニーズに合わせて建て増しで改修されていたために、拡張性や汎⽤性が低下
    • 独⾃仕様が多くあり、開発者の負担の増加
    API 2.0 の⽬的
    • 利⽤しやすく、シンプルで、安定した API に改善。
    12
    

    View Slide

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
    

    View Slide

13. 変更点 1. サービス API / サーバー API の区分の撤廃
    14
    API が⽤途によって2種類に分類されていました。
    API 1.0
    • どちらに区分されているか1つ1つ意識する必要があり、使い勝⼿に影響していました。
    • また、API 全体の複雑さにも起因していました。
    サービス API サーバー API
    Drive
    メール
    カレンダー
    アドレス帳
    メール
    カレンダー
    トークBot
    組織連携
    掲⽰板
    Webアプリ等に組み込んで
    ユーザーが利⽤する。
    チャットボットやバッチ処理等で
    システムが利⽤する。
    

    View Slide

14. 変更点 1. サービス API / サーバー API の区分の撤廃
    15
    API 2.0
    サービス API / サーバー API の区分を撤廃し1つにまとめ、各APIがどちらに区分されているの
    か意識する必要がなくなりました。
    また、アクセストークンの取得プロセスについても、改めて再定義しました (詳細は後述)
    アドレス帳
    メール
    カレンダー
    トークBot
    組織連携
    掲⽰板
    Drive
    API
    

    View Slide

15. 変更点 2. API 構造/形式の単純化
    • 全体的に構造が複雑であり、予測可能でない形となっていました。
    • カテゴリごとに形式がバラバラ
    • 類似 API の重複
    • コンテンツのアップロード・ダウンロードの⽅式がバラバラ
    • など
    16
    API 1.0
    API 2.0
    • これらの問題を解消するよう、API 全体の構造や形式を整理しました。
    API の構造や形式に関する改善点について、いくつか例を出して説明します。
    

    View Slide

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⾃体を廃⽌。
    

    View Slide

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 カテゴリに統合。形式も統⼀。
    

    View Slide

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
    

    View Slide

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が複数存在。
    

    View Slide

20. 変更点 2. API 構造/形式の単純化
    21
    API 1.0
    例. コンテンツのアップロード・ダウンロードの⽅式がバラバラ
    URLやリクエストボディ/ヘッダー、
    ファイルデータの指定⽅法等がそれぞれ異なっていた。
    API 2.0
    形式やフローを統⼀
    アップロードのフローについて
    

    View Slide

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
    メール
    カレンダー
    

    View Slide

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を利⽤する場合。
    

    View Slide

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
    

    View Slide

24. 変更点 3. アクセストークン取得プロセスの刷新
    25
    1.アクセストークンの⾃動延⻑機能の廃⽌。
    • リフレッシュトークンを⽤いて再発⾏を⾏う形に統⼀しました。
    2.「アプリ」の導⼊。
    • API利⽤のための認証情報・権限の管理はこのアプリで⾏います。
    • アプリは、⽤途に分けて複数作成することができます。
    3.各認証情報をOAuth2.0ベースの名称に変更。
    • Client ID, Client Secret, Scope, etc
    その他 API 認証周りの変更事項
    

    View Slide

25. その他変更点については
    26
    Developers Document にも API 間の違いに関するドキュメントがあります。
    今回説明できなかった細かい変更点についても説明されています。
    https://developers.worksmobile.com/jp/reference/difference-between-api?lang=ja
    

    View Slide

26. 変更されていないこと
    27
    1. SSO
    2. SAML Apps
    3. LINE WORKSログイン
    4. IPT
    5. App Link
    6. トークBotの登録プロセス
    これらは API 1.0 / API 2.0 の項⽬ではなく、今回の API アップデートでも変更対象外です。
    

    View Slide

27. 4. API 2.0 のデモ
    28
    

    View Slide

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上で私宛に連絡ください。
    

    View Slide

29. その他 実装例
    • Bubble.ioでの実装例
    • https://qiita.com/mmclsntr/items/a9654a6480cb82f6f06b
    • PythonでのService Account認証実装例
    • https://qiita.com/mmclsntr/items/0c118f40ffe7f36cd4eb
    30
    ※ 私個⼈で作成して公開したものです。不具合等あれば上記GithubやQiita上で私宛に連絡ください。
    

    View Slide

30. 5. API 2.0 への移⾏のお願い
    31
    

    View Slide

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
    

    View Slide

32. Developers Documents
    33
    APIリファレンスは「LINE WORKS Developers」のドキュメントにあります。
    https://developers.worksmobile.com/jp/?lang=ja
    

    View Slide

33. Developers Community
    34
    API について疑問点などありましたら、コミュニティもぜひご活⽤ください。
    https://forum.worksmobile.com/jp/
    

    View Slide

34. View Slide