• Deutsch

      • Benutzerdaten aus Feishu synchronisieren

      Einführung

      Das Feishu / Lark Plugin synchronisiert Benutzer und Abteilungen einer Feishu-Organisation nach NocoBase. Es unterstützt die vollständige Synchronisierung auf Anforderung sowie inkrementelle Aktualisierungen per HTTP-Callback oder Stream-Verbindung.

      Vorbereitung

      1. Installieren und aktivieren Sie die Plugins Feishu / Lark und Benutzerdatensynchronisierung.
      2. Erstellen Sie eine unternehmensinterne App auf der Feishu Open Platform, siehe Authentifizierung: Feishu / Lark.
      3. Aktivieren Sie die Kontakt-Berechtigungen und konfigurieren Sie den Sichtbarkeitsbereich wie unten beschrieben.

      Kontakt-Berechtigungen und Sichtbarkeitsbereich

      Aktivieren Sie unter Berechtigungen der App die folgenden Rechte:

      BerechtigungScopeErforderlichZweck
      Benutzergrunddaten abrufencontact:user.base:readonlyJaLiest Namen, open_id / union_id und weitere Grundfelder.
      Abteilungsgrunddaten abrufencontact:department.base:readonlyJaLiest Abteilungsnamen und Hierarchie.
      Abteilungsorganisationsstruktur abrufencontact:department.organize:readonlyJaDurchläuft Unterabteilungen; liest Abteilungsleiter.
      Benutzerorganisationsstruktur abrufencontact:user.department:readonlyJaLiest Abteilungen und Hauptabteilung des Benutzers.
      Benutzer-User-ID abrufencontact:user.id:readonlyFür Kennzeichen user_idLiest das Feld user_id.
      Benutzertelefonnummer abrufencontact:user.phone:readonlyFür Telefon-SyncLiest Telefonnummern; erforderlich bei Kennzeichen mobile.
      Benutzer-E-Mail abrufencontact:user.email:readonlyFür E-Mail-SyncLiest E-Mails; erforderlich bei Kennzeichen email.

      Konfigurieren Sie anschließend den Berechtigungsbereich für Kontakte (welche Abteilungen und Mitglieder die App sehen darf):

      1. Klicken Sie auf der Seite Entwicklungskonfiguration → Berechtigungen rechts in der Spalte „Zugänglicher Datenbereich" auf Konfigurieren (beim Aktivieren einer Kontakt-Berechtigung wird automatisch dorthin gesprungen).
      2. Wählen Sie die Abteilungen und Mitglieder; für die Ersteinrichtung empfiehlt sich Alle Mitglieder, danach bei Bedarf eingrenzen.
      3. Klicken Sie auf OK.
      Warning

      Ohne Benutzergrunddaten abrufen liefert die API keine Namen und die synchronisierten Spitznamen bleiben leer. Der Berechtigungsbereich für Kontakte und die „Verfügbarkeitsbereich der App" (wer die App nutzen darf) sind zwei unabhängige Einstellungen — nur ersterer beeinflusst die Synchronisierung. API-Berechtigungen bestimmen die lesbaren Felder, der Berechtigungsbereich die lesbaren Abteilungen und Benutzer; beides ist zu konfigurieren. Nach Änderungen eine vollständige Synchronisierung erneut ausführen. Event-Abonnement ersetzt keine Leseberechtigungen: NocoBase ruft bei jedem Event die aktuellen Daten über die Feishu-API ab.

      Feishu-Sync-Quelle hinzufügen

      Öffnen Sie Benutzer & Berechtigungen → Synchronisierung und fügen Sie eine Quelle vom Typ Feishu / Lark hinzu:

      FeldBeschreibung
      QuellennameEindeutiger Name der Sync-Quelle.
      AktiviertStartet den Ereignisempfang der Quelle und erlaubt Sync-Aufgaben.
      RegionFeishu China oder Lark Global.
      App ID / App SecretZugangsdaten der Feishu-App. Umgebungsvariablen und Secrets werden unterstützt.
      Eindeutiges Benutzerkennzeichen-Felduser_id, union_id, open_id, mobile oder email; empfohlen union_id. Muss mit dem Authenticator übereinstimmen; Benutzer ohne Wert werden übersprungen.
      Ereignis-EmpfangsmodusHTTP-Callback oder Stream-Modus, siehe unten.

      Speichern und aktivieren Sie die Quelle und klicken Sie auf Synchronisieren für die erste vollständige Synchronisierung.

      Wahl des Ereignis-Empfangsmodus

      Stream-Modus

      Der Stream-Modus hält eine dauerhafte WebSocket-Verbindung, die vom NocoBase-Server initiiert wird. Keine öffentliche Callback-URL, kein Token, kein Verschlüsselungsschlüssel.

      1. Wählen Sie in NocoBase Stream-Modus, speichern und aktivieren Sie die Quelle.
      2. Stellen Sie auf der Plattform unter Ereignisse & Callbacks den Empfang auf Long Connection (WebSocket) um und abonnieren Sie die Kontakt-Ereignisse.

      Die Verbindung startet automatisch beim Aktivieren (mit automatischer Wiederverbindung) und wird bei Änderung, Deaktivierung oder Löschung der Quelle aktualisiert oder geschlossen.

      Info

      Der Stream-Modus benötigt keine öffentliche eingehende Adresse und keinen Reverse-Proxy — geeignet für Intranet-Installationen. Der Verbindungsstatus ist in den Anwendungslogs unter Feishu stream client prüfbar.

      HTTP-Callback

      1. Wählen Sie in NocoBase HTTP-Callback und konfigurieren Sie Verification Token und optional Encrypt Key — mindestens eines ist erforderlich.
      2. Speichern Sie die Quelle und kopieren Sie die angezeigte Ereignis-Callback-URL.
      3. Konfigurieren Sie auf der Plattform unter Ereignisse & Callbacks → Ereigniskonfiguration den Empfang per Server-Push, fügen Sie die URL ein und abonnieren Sie die Kontakt-Ereignisse.

      Die Callback-URL muss von Feishu erreichbar sein (in Produktion HTTPS). Mit Encrypt Key werden Callback-Inhalte verschlüsselt.

      Warning

      Ohne Verification Token oder Encrypt Key werden Callback-Anfragen abgelehnt (401). Nach Umstellung einer Quelle auf den Stream-Modus wird der HTTP-Endpunkt geschlossen (403).

      Unterstützte inkrementelle Ereignisse

      EreignisVerarbeitung in NocoBase
      contact.user.created_v3Benutzer erstellen oder aktualisieren.
      contact.user.updated_v3Benutzer aktualisieren.
      contact.user.deleted_v3Synchronisierten Benutzer löschen.
      contact.department.created_v3Abteilung erstellen oder aktualisieren.
      contact.department.updated_v3Abteilung aktualisieren.
      contact.department.deleted_v3Synchronisierte Abteilung löschen.

      Benutzer mit der Root-Rolle werden durch die Synchronisierung nie gelöscht.

      Synchronisierte Felder

      Abteilungsfelder

      Feishu-FeldNocoBase-Feld / Zweck
      open_department_idEindeutiger Quell-Bezeichner der Abteilung.
      nameAbteilungsname.
      parent_department_idÜbergeordnete Abteilung für die Hierarchie. Abteilungen mit Eltern außerhalb des Bereichs werden als Wurzel synchronisiert.

      Benutzerfelder

      Feishu-FeldNocoBase-Feld / Zweck
      Wert des Kennzeichen-FeldsQuell-Bezeichner und Benutzername aus dem eindeutigen Kennzeichen-Feld.
      name, sonst en_nameSpitzname; bleibt leer, wenn beides fehlt.
      mobileTelefonnummer.
      emailE-Mail.
      department_idsAbteilungen des Benutzers; nur innerhalb des Sichtbarkeitsbereichs.
      main_department_idHauptabteilung.

      Abteilungsleiter

      Abteilungsleiter aus den Abteilungsdaten werden als Abteilungsverantwortliche synchronisiert: Ein Benutzer kann mehrere Abteilungen leiten, und eine geleitete Abteilung muss nicht die Hauptabteilung sein. Es werden nur Abteilungen im Sichtbarkeitsbereich berücksichtigt. Entfernte Leiter werden bei der nächsten Synchronisierung entfernt; manuell in NocoBase geänderte Leiter können überschrieben werden.

      Andere Feishu-Benutzerfelder wie Avatar, Position und Personalnummer werden derzeit nicht synchronisiert.

      Fehlerbehebung

      • Leere Ergebnisse oder fehlende Abteilungen: Kontakt-Berechtigungen und Sichtbarkeitsbereich prüfen.
      • Leere Spitznamen: Benutzergrunddaten abrufen (contact:user.base:readonly) aktivieren und vollständig synchronisieren.
      • Übersprungene Benutzer: Vorhandensein des Kennzeichen-Werts und Übereinstimmung mit dem Authenticator prüfen.
      • HTTP-Callback 401: Verification Token / Encrypt Key fehlen oder sind falsch; 403: Quelle wurde in den Stream-Modus umgestellt.
      • Fehler zu redirect_uri oder Callback-URL: Adresse auf der Plattform muss exakt der in NocoBase angezeigten entsprechen (einschließlich APP_PUBLIC_PATH-Präfix).
      • Sync-Aufgabe scheitert an API-Rate-Limit: Limit abwarten und Synchronisierung manuell erneut ausführen.