組織連携(Directory)API 概要

    組織連携

    組織連携とは、メンバーや組織、役職、職級などの組織情報をAPI 2.0の組織連携(Directory)APIを使用してLINE WORKSと同期するための機能です。
    Directory APIを使用すると、メンバーや組織、役職、職級などの情報を操作することができます。

    ここでは API 2.0とAPI 1.0の組織連携の違い、およびAPI 2.0 Directory APIを使用した組織連携方法やについて説明します。

    API 1.0 とAPI 2.0 の組織連携の違い

    項目 API 1.0 API 2.0
    Developer Console > 組織連携の使用設定 必須 任意
    データアクセスキー ExternalKeyのみ リソースID(userId/orgUnitId/groupId/etc.)またはExternalKey
    ステータスAPI 不在機能のみ利用可能 すべて利用可能
    External Key Mapping 必須 任意
    メンバー即時削除API Developer Consoleで設定後、利用可能 無条件で利用可能
    メンバーリスト照会API Developer Consoleで設定後、利用可能 無条件で利用可能

    注意

    • 同じ組織データへ API 1.0, API 2.0 両方からアクセスすることができますが、混用せず1つのAPIで実装してください。
    • API 1.0は提供終了を予定しています。API 2.0への移行をご検討ください。

    Developer Consoleの組織連携メニュー

    Developer Consoleの組織連携メニューでは以下の設定ができます。

    組織連携の使用設定

    API 1.0では、組織連携の使用設定をONに切り替えた場合のみ組織連携APIを使用できましたが、API 2.0では組織連携の使用設定のON/OFFに関わらず使用できます。 API 2.0で管理者画面からの操作による組織データ競合を回避したい場合は、組織連携使用設定をONにすることで、管理者画面からの操作を禁止することができます。

    組織連携の使用設定による管理者画面の動作

    • 組織連携の使用設定設定を Off から On に変更すると、管理者画面で「リンク/QRコードによる招待」機能が無効になり、承認待ちのメンバーは全て削除されます。
    • 組織/構成員を On に設定すると、管理者画面のメンバーおよび組織のメニューは参照のみに制限されます。ただし、Developer Consoleで「チームで利用する機能」を許可している場合、管理者画面からチームの各機能を設定できます。
    • 職級/役職を On に設定すると、管理者画面から職級/役職のメニューが非表示になります。
    • グループを On に設定すると、管理者画面で"グループリスト"は参照のみに制限されます。ただし、「管理者およびユーザーにグループの修正を可能にする。」設定を有効にすると、管理者画面からグループの各機能を設定できます。
    • 利用権限タイプを On に設定すると、管理者画面で利用権限タイプが非表示になります。

    組織連携の使用設定によるユーザー情報ポップアップ

    • 組織/構成員を On に設定する際、メンバー自身によるプロフィール写真の変更を許可するか選択できます。
    • 使用言語を On に設定すると、ユーザー情報ポップアップに言語·時間帯が表示されなくなります。
    • 不在設定を On に設定すると、ユーザー情報ポップアップにステータスが表示されなくなります。

    組織リソースデータへのアクセス

    API 2.0の組織、メンバー、グループ、利用権限タイプ、職級、役職、ステータスのリソースデータにアクセスする方法は、以下の２つです。

    1. LINE WORKSが発行したリソースIDによるアクセス (推薦)
      各組織リソースを登録する際、LINE WORKSが自動で発行するリソースID(userId/orgUnitId/groupId/etc.)を使用してアクセスすることができます。

    2. API利用者側で発行したExternalKeyによるアクセス
      社内システム等で使用している各組織のリソースIDをExternalKeyに設定してアクセスすることができます。

      注意　（ExternalKeyの制限）

      • ExternalKeyに「%」,「#」,「/」,「?」の特殊文字は使用できません
      • 組織、メンバー、グループ、利用権限タイプは、テナント内で一意である必要があります
      • 職級、役職、カスタムフィールドは、ドメイン内で一意である必要があります。

    組織連携APIの使用準備

    組織連携を利用する場合は下記の準備が必要です。詳細はAPI 2.0の Using APIsを参照してください。

    • Directory scopeを含むアプリ
    • Service Accountの発行
    • Developer Consoleの組織連携設定 (任意)

    組織連携APIの呼び出しフロー(推奨)

    「組織連携APIの使用準備」の作業を終えたら、組織連携APIを使用できるようになります。

    • 組織連携（Directory）APIを利用した連携をバッチ処理することを推奨します。

    ALT

    図1 組織連携バッチの流れ

    • 組織連携は日(day)単位でバッチ処理することを推奨します。
    • 各段階で失敗した際のロールバックはクライアントの社内ポリシーに従って適用してください。
    • バッチ処理中に一部の変更が失敗した場合は引き続き処理を進行し、すべてが失敗した場合は処理を中断することを推奨します。
    • 組織(Orgunit)データは必ずシングルスレッドで 1 秒に 1 回、順番通りに呼び出すことを推奨します。