• 日本語

      • Feishu からユーザーデータを同期する

      はじめに

      Feishu / Lark プラグインは、Feishu 組織のユーザーと部署を NocoBase に同期します。手動の全件同期に加え、HTTP コールバックまたは Stream 接続による差分更新に対応します。

      事前準備

      1. Feishu / Lark と ユーザーデータ同期 プラグインをインストールして有効化します。
      2. Feishu オープンプラットフォームで企業自社アプリを作成します。詳細は認証：Feishu / Larkを参照。
      3. 下記の連絡先権限を有効化し、連絡先の権限範囲を設定します。

      連絡先権限と権限範囲

      アプリの権限管理で以下の権限を有効にします：

      権限スコープ必須用途
      ユーザーの基本情報を取得contact:user.base:readonlyはい名前、open_id / union_id などの基本フィールドを読み取ります。
      部門の基本情報を取得contact:department.base:readonlyはい部門名と階層を読み取ります。
      部門の組織構造を取得contact:department.organize:readonlyはい子部門を走査し、部門責任者を読み取ります。
      ユーザーの組織構造を取得contact:user.department:readonlyはいユーザーの所属部署と主部署を読み取ります。
      ユーザーの user ID を取得contact:user.id:readonly識別子が user_id の場合user_id フィールドを読み取ります。
      ユーザーの電話番号を取得contact:user.phone:readonly電話同期の場合電話番号を読み取ります。識別子が mobile の場合に必須。
      ユーザーのメールを取得contact:user.email:readonlyメール同期の場合メールを読み取ります。識別子が email の場合に必須。

      続けて連絡先権限範囲（アプリがアクセスできる部署とメンバー）を設定します：

      1. 開発設定 → 權限管理ページの「アクセス可能なデータ範囲」列の設定をクリックします（連絡先権限を有効化すると自動的に遷移します）。
      2. アクセスを許可する部署とメンバーを選択します。初回は全メンバーを推奨し、動作確認後に絞り込みます。
      3. OK をクリックして保存します。
      Warning

      ユーザーの基本情報を取得がない場合、API は名前を返さず、同期後のニックネームが空になります。連絡先権限範囲と「アプリの利用可能範囲」（誰がアプリを使えるか）は別の設定であり、同期に影響するのは前者だけです。API 権限は読み取り可能なフィールドを、権限範囲は読み取り可能な部署とユーザーを決めます。両方の設定が必要で、変更後は全件同期を再実行してください。イベント購読は読み取り権限の代わりにはなりません。NocoBase はイベントごとに Feishu API で最新データを取得します。

      Feishu 同期ソースを追加

      ユーザーと権限 → 同期で Feishu / Lark タイプのソースを追加します：

      項目説明
      ソース名同期ソースの一意な名前。
      有効ソースのイベント受信を開始し、同期タスクの実行を許可します。
      地域Feishu China または Lark Global。
      App ID / App SecretFeishu アプリの資格情報。環境変数とシークレットに対応。
      ユーザー一意識別子フィールドuser_id、union_id、open_id、mobile、email。推奨は union_id。認証器と一致させてください。該当値を持たないユーザーはスキップされます。
      イベント受信方式HTTP コールバック または Stream モード。下記を参照。

      保存して有効化した後、同期をクリックして初回の全件同期を行います。

      イベント受信方式の選択

      Stream モード

      Stream モードは NocoBase サーバーから WebSocket の常時接続を維持します。公開コールバック URL やトークン・暗号鍵は不要です。

      1. NocoBase で Stream モードを選択し、保存して有効化します。
      2. プラットフォームのイベントとコールバックで受信方式をロングコネクション（WebSocket）に切り替え、連絡先イベントを購読します。

      接続はソースの有効化時に自動で開始され（自動再接続付き）、ソースの更新・無効化・削除時に更新または切断されます。

      Info

      Stream モードは公開の受信アドレスもリバースプロキシも不要で、イントラネット運用に適します。接続状態はアプリログで Feishu stream client を検索して確認できます。

      HTTP コールバック

      1. NocoBase で HTTP コールバックを選択し、Verification Token と任意で Encrypt Key を設定します。少なくとも一方が必要です。
      2. ソースを保存し、画面に表示されたイベントコールバック URL をコピーします。
      3. プラットフォームのイベントとコールバック → イベント設定で、サーバーへの送信方式を選択し、URL を貼り付けて連絡先イベントを購読します。

      コールバック URL は Feishu から到達可能である必要があります（本番環境では HTTPS）。Encrypt Key を設定するとコールバック内容は暗号化されます。

      Warning

      Verification Token または Encrypt Key がない場合、コールバックリクエストは拒否されます（401）。ソースを Stream モードに切り替えると HTTP エンドポイントは閉じられます（403）。

      対応する差分イベント

      イベントNocoBase での処理
      contact.user.created_v3ユーザーを作成または更新。
      contact.user.updated_v3ユーザーを更新。
      contact.user.deleted_v3同期済みユーザーを削除。
      contact.department.created_v3部署を作成または更新。
      contact.department.updated_v3部署を更新。
      contact.department.deleted_v3同期済み部署を削除。

      Root ロールを持つユーザーは同期では削除されません。

      同期フィールド

      部署フィールド

      Feishu フィールドNocoBase のフィールド／用途
      open_department_id部署のソース一意識別子。
      name部署名。
      parent_department_id親部署（階層構造の構築用）。親が範囲外の部署はルートとして同期されます。

      ユーザーフィールド

      Feishu フィールドNocoBase のフィールド／用途
      識別子フィールドの値ユーザー一意識別子フィールドからソース識別子とユーザー名を生成。
      name、なければ en_nameニックネーム。両方欠落時は空。
      mobile電話番号。
      emailメール。
      department_idsユーザーの所属部署。権限範囲内のみ。
      main_department_id主部署。

      部門責任者

      部署データの責任者（リーダー）は NocoBase の部門責任者として同期されます。1 ユーザーが複数部署の責任者になれるほか、責任者部署が主部署とは限りません。対象は権限範囲内の部署のみです。Feishu 側で解除された責任者は次回の同期で解除され、NocoBase で手動変更した責任者が上書きされる場合があります。

      アバター・役職・社員番号などのその他フィールドは現在同期されません。

      トラブルシューティング

      • 同期結果が空、部署が欠ける：連絡先権限と権限範囲を確認。
      • ニックネームが空：ユーザーの基本情報を取得（contact:user.base:readonly）を有効化し、全件同期を再実行。
      • ユーザーがスキップされる：識別子フィールドの値の有無と、認証器との一致を確認。
      • HTTP コールバックが 401：Verification Token / Encrypt Key の未設定または不一致。403：ソースが Stream モードに切り替わっています。
      • redirect_uri やコールバック URL のエラー：プラットフォームの URL が NocoBase 表示と完全一致しているか（APP_PUBLIC_PATH プレフィックス含む）確認。
      • API レート制限で同期タスクが失敗：制限解除後に手動で再実行。