• Русский

      • Синхронизация пользовательских данных из Feishu

      Feishu / LarkProfessional Edition+

      Введение

      Плагин Feishu / Lark синхронизирует пользователей и отделы организации Feishu с NocoBase. Поддерживаются ручная полная синхронизация и инкрементальные обновления через HTTP callback или соединение Stream.

      Перед началом работы

      1. Установите и включите плагины Feishu / Lark и Синхронизация пользовательских данных.
      2. Создайте корпоративное приложение на открытой платформе Feishu, см. Аутентификация: Feishu / Lark.
      3. Выдайте права на чтение контактов и настройте область видимости контактов, как описано ниже.

      Права на контакты и область видимости

      В разделе Права приложения включите следующие права:

      ПравоИдентификатор (scope)ОбязательностьНазначение
      Получение базовой информации о пользователеcontact:user.base:readonlyДаЧитает имя пользователя, open_id / union_id и другие базовые поля; без него API не возвращает имена, и никнеймы после синхронизации будут пустыми.
      Получение базовой информации об отделе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.
      Получение email пользователяcontact:user.email:readonlyДля синхронизации emailЧитает email; обязательно при идентификаторе email.

      Затем настройте область прав на контакты(какие отделы и сотрудники доступны приложению):

      1. На странице Конфигурация разработки → Права нажмите Настроить справа от колонки «Доступная область данных» у контакта(при включении права на контакты страница открывается автоматически).
      2. Выберите отделы и сотрудников, доступных приложению. При первой настройке рекомендуется выбрать всех сотрудников, а после проверки — сузить при необходимости.
      3. Нажмите ОК для сохранения.
      Warning

      Область прав на контакты и «область доступности приложения»(кто может использовать приложение)— две независимые настройки, не путайте их; на синхронизацию данных влияет только область прав на контакты. Права API определяют, какие поля может читать приложение, а область прав на контакты — какие отделы и пользователей; настроить нужно и то, и другое. Область синхронизации следует области прав; после изменения выполните полную синхронизацию заново. Подписка на события не заменяет права на чтение: при каждом событии NocoBase всё равно запрашивает актуальные данные через API Feishu.

      Добавление источника синхронизации Feishu

      Перейдите в Пользователи и права → Синхронизация и добавьте источник типа Feishu / Lark:

      ПолеОписание
      Имя источникаУникальное имя источника синхронизации.
      ВключеноЗапускает прием событий источника и позволяет выполнять задачи синхронизации.
      РегионFeishu China или Lark Global.
      App ID / App SecretУчетные данные приложения Feishu. Поддерживаются переменные окружения и секреты.
      Поле уникального идентификатора пользователяuser_id, union_id, open_id, mobile или email; рекомендуется union_id. Должно совпадать с аутентификатором; пользователи без значения выбранного поля пропускаются.
      Способ приема событийHTTP callback или режим Stream, см. ниже.

      Сохраните и включите источник, затем нажмите Синхронизировать для первой полной синхронизации.

      Выбор способа приема событий

      Режим Stream

      Режим Stream поддерживает постоянное WebSocket-соединение, инициируемое сервером NocoBase. Публичный адрес обратного вызова, токен и ключ шифрования не требуются.

      1. Выберите режим Stream в NocoBase, сохраните и включите источник.
      2. На платформе в разделе События и обратные вызовы переключите способ приема на длинное соединение (WebSocket) и подпишитесь на события контактов.

      Соединение запускается автоматически при включении источника (с автоматическим переподключением) и обновляется или закрывается при изменении, отключении или удалении источника.

      Info

      Режим Stream не требует публичного входящего адреса и обратного прокси — подходит для внутрисетевых развёртываний. Статус соединения можно проверить в журналах приложения по строке Feishu stream client.

      HTTP callback

      Режим HTTP callback принимает события Feishu по адресу обратного вызова NocoBase.

      1. Выберите HTTP callback в NocoBase и задайте Verification Token и, при необходимости, Encrypt Key — требуется хотя бы один.
      2. Сохраните источник и скопируйте URL обратного вызова событий из интерфейса.
      3. На платформе в разделе События и обратные вызовы → Настройка событий выберите отправку событий на сервер, вставьте URL и подпишитесь на события контактов.

      Адрес обратного вызова должен быть доступен для Feishu (в продакшене — HTTPS). При настроенном Encrypt Key содержимое обратных вызовов шифруется.

      Warning

      Без Verification Token или Encrypt Key запросы отклоняются (401). После перевода источника в режим Stream HTTP-эндпоинт закрывается (403).

      Поддерживаемые инкрементальные события

      Оба способа поддерживают следующие события контактов Feishu:

      СобытиеОбработка в 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Телефон.
      emailEmail.
      department_idsОтделы пользователя; только в пределах области видимости.
      main_department_idОсновной отдел.

      Руководители отделов

      Руководители отделов (лидеры) из данных отделов синхронизируются как владельцы отделов в NocoBase: пользователь может руководить несколькими отделами, и руководимый отдел не обязан быть основным. Участвуют только отделы в области видимости. Снятые на стороне Feishu руководители снимаются при следующей синхронизации; вручную измененные в NocoBase руководители могут быть перезаписаны.

      Другие поля пользователя Feishu (аватар, должность, табельный номер) в настоящее время не синхронизируются.

      Устранение неполадок

      • Пустые результаты или отсутствующие отделы: проверьте права на чтение контактов и наличие отдела в области прав на контакты (настройка описана выше).
      • Пустые никнеймы: включите право Получение базовой информации о пользователе (contact:user.base:readonly) и выполните полную синхронизацию заново.
      • Пользователи пропускаются: проверьте наличие у пользователя значения выбранного поля идентификатора и его совпадение с аутентификатором.
      • HTTP callback возвращает 401: не настроен Verification Token или Encrypt Key, либо проверка токена не прошла; 403: источник переведен в режим Stream.
      • Ошибки redirect_uri или адреса обратного вызова: убедитесь, что адрес на платформе точно совпадает с показанным в NocoBase, включая префикс вложенного пути (APP_PUBLIC_PATH).
      • Задача синхронизации завершается ошибкой лимита API Feishu: дождитесь снятия ограничения и запустите синхронизацию вручную еще раз.