Box-Konnektor

Übersicht

Der Box-Konnektor bietet die Funktionalität, Dateien aus dem Box.com-Cloud-Speicher abzurufen und im Fess-Index zu registrieren.

Dieser Konnektor verbindet sich mit dem Unternehmen mittels JWT (Server Authentication) und crawlt rekursiv die Dateien, auf die jeder Benutzer im Unternehmen zugreifen kann, indem er den jeweiligen Benutzer impersoniert. Die zu crawlenden Benutzer können mit dem Parameter filter_term eingeschränkt werden.

Für diese Funktion ist das Plugin fess-ds-box erforderlich.

Voraussetzungen

  1. Die Installation des Plugins ist erforderlich

  2. Ein Box-Entwicklerkonto und eine Anwendung müssen erstellt werden

  3. Die Konfiguration der JWT-Authentifizierung (JSON Web Token) ist erforderlich

Plugin-Installation

Methode 1: JAR-Datei direkt platzieren

# Von Maven Central herunterladen
wget https://repo1.maven.org/maven2/org/codelibs/fess/fess-ds-box/X.X.X/fess-ds-box-X.X.X.jar

# Platzieren
cp fess-ds-box-X.X.X.jar $FESS_HOME/app/WEB-INF/lib/
# oder
cp fess-ds-box-X.X.X.jar /usr/share/fess/app/WEB-INF/lib/

Methode 2: Über die Administrationsoberfläche installieren

  1. Öffnen Sie „System“ -> „Plugins“

  2. Laden Sie die JAR-Datei hoch

  3. Starten Sie Fess neu

Konfiguration

Konfigurieren Sie über die Administrationsoberfläche unter „Crawler“ -> „Datenspeicher“ -> „Neu erstellen“.

Grundeinstellungen

Einstellung Beispielwert
Name Company Box Storage
Handler-Name BoxDataStore
Aktiviert Ein

Parameter-Einstellungen

Beispiel für JWT-Authentifizierung:

client_id=hdf8a7sd9f8a7sdf9a87sdf98a7sd
client_secret=kMN7sd8f7a9sd8f7a9sd8f7a9sd8f
public_key_id=4tg5h6j7
private_key=<YOUR_PRIVATE_KEY>
passphrase=7ba8sd9f7a9sd8f7a9sd8f7a9sd8f
enterprise_id=1923456

Parameterliste

Authentifizierungsparameter (erforderlich)
Crawl-Parameter (optional)
Parameter Standardwert Beschreibung
max_size 10000000 Maximale Dateigröße für das Crawling (Bytes). Standard ist 10 MB.
supported_mimetypes .* MIME-Typen für das Crawling (regulärer Ausdruck). Mehrere Werte können durch Komma getrennt angegeben werden.
include_pattern (keine) URL-Muster, die in das Crawling eingeschlossen werden sollen
exclude_pattern (keine) URL-Muster, die vom Crawling ausgeschlossen werden sollen
number_of_threads 1 Anzahl der Threads für die Crawl-Verarbeitung
ignore_folder true Gibt an, ob Ordner von der Indexierung ausgeschlossen werden sollen. In der aktuellen Implementierung werden Ordner selbst nicht indexiert (nur Dateien werden erfasst), daher hat dieser Parameter keine Auswirkung.
ignore_error true Gibt an, ob die Verarbeitung bei einem Fehler fortgesetzt werden soll
filter_term (keine) Filterbedingung zur Einschränkung der zu crawlenden Unternehmensbenutzer. Wenn nicht angegeben, werden alle Unternehmensbenutzer erfasst.
fields (alle Felder) Angabe der Felder, die über die Box API abgerufen werden sollen
Verbindungsparameter (optional)
Parameter Standardwert Beschreibung
base_url https://app.box.com Basis-URL zur Konstruktion der URL zum Öffnen einer Datei im Browser (file.url). Die vom Box SDK verwendeten API-Endpunkte werden dadurch nicht beeinflusst.
max_retry_count 10 Maximale Anzahl von Wiederholungsversuchen für API-Aufrufe
proxy_host (keine) Hostname des HTTP-Proxys
proxy_port (keine) Portnummer des HTTP-Proxys
refresh_token_interval 3540 Intervall für die Token-Aktualisierung (Sekunden). Standard ist 59 Minuten.

Skript-Einstellungen

url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at

Verfügbare Felder

Hauptfelder
Feld Beschreibung
file.url Link zum Öffnen der Datei im Browser
file.contents Textinhalt der Datei
file.mimetype MIME-Typ der Datei
file.filetype Dateityp
file.name Dateiname
file.size Dateigröße (Bytes)
file.created_at Erstellungsdatum
file.modified_at Datum der letzten Änderung
file.download_url Direkter Box-Download-URL
file.id Box-Element-ID
file.description Dateibeschreibung
file.extension Dateiendung
file.sha1 SHA1-Hash der Datei
file.path_collection Liste der Ordnerpfade
Metadatenfelder
Feld Beschreibung
file.type Elementtyp („file“ oder „folder“)
file.file_version Dateiversion-Informationen
file.sequence_id Sequenz-ID
file.etag ETag-Hash
file.trashed_at Datum der Verschiebung in den Papierkorb
file.purged_at Datum der endgültigen Löschung
file.content_created_at Erstellungsdatum des Inhalts
file.content_modified_at Änderungsdatum des Inhalts
file.created_by Informationen zum Ersteller
file.modified_by Informationen zum letzten Bearbeiter
file.owned_by Informationen zum Eigentümer
file.shared_link Freigegebene Link-Informationen
file.parent Informationen zum übergeordneten Ordner
file.item_status Elementstatus
file.version_number Versionsnummer
file.comment_count Anzahl der Kommentare
file.permissions Berechtigungsinformationen
file.tags Tag-Informationen
file.lock Sperrinformationen
file.is_package Paket-Flag
file.is_watermark Wasserzeichen-Flag
file.collections Sammlungsinformationen
file.representations Darstellungsformat-Informationen
file.api Box-Datei-API-Objekt (für den Abruf von Kollaborations- und Berechtigungsinformationen)

Weitere Details finden Sie unter Box File Object.

Box-Authentifizierung konfigurieren

Schritte zur JWT-Authentifizierung

1. Anwendung in der Box Developer Console erstellen

Besuchen Sie https://app.box.com/developers/console:

  1. Klicken Sie auf „Create New App“

  2. Wählen Sie „Custom App“

  3. Wählen Sie als Authentifizierungsmethode „Server Authentication (with JWT)“

  4. Geben Sie den App-Namen ein und erstellen Sie sie

2. Anwendungskonfiguration

Konfigurieren Sie im Tab „Configuration“:

Application Scopes:

  • Aktivieren Sie „Read all files and folders stored in Box“

Advanced Features:

  • Klicken Sie auf „Generate a Public/Private Keypair“

  • Laden Sie die generierte JSON-Datei herunter (wichtig!)

App Access Level:

  • Wählen Sie „App + Enterprise Access“

3. Enterprise-Genehmigung

In der Box Admin-Konsole:

  1. Öffnen Sie „Apps“ -> „Custom Apps“

  2. Genehmigen Sie die erstellte App

4. Authentifizierungsinformationen abrufen

Rufen Sie die folgenden Informationen aus der heruntergeladenen JSON-Datei ab:

{
  "boxAppSettings": {
    "clientID": "hdf8a7sd...",         // client_id
    "clientSecret": "kMN7sd8f...",      // client_secret
    "appAuth": {
      "publicKeyID": "4tg5h6j7",        // public_key_id
      "privateKey": "-----BEGIN...",    // private_key
      "passphrase": "7ba8sd9f..."       // passphrase
    }
  },
  "enterpriseID": "1923456"             // enterprise_id
}

Format des privaten Schlüssels

private_key wird in eine Zeile umgewandelt, wobei Zeilenumbrüche durch \n ersetzt werden:

private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgk...=\n-----END ENCRYPTED PRIVATE KEY-----\n

Anwendungsbeispiele

Gesamten Box-Speicher des Unternehmens crawlen

Parameter:

client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789

Skript:

url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at

Nur bestimmte Ordner crawlen

Mit dem Parameter include_pattern ist eine Filterung nach Ordnerpfaden möglich.

Parameter:

client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789
include_pattern=.*Documents/Projects/.*

Skript:

url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at

Nur PDF-Dateien crawlen

Mit dem Parameter supported_mimetypes ist eine Filterung nach MIME-Typ möglich.

Parameter:

client_id=abc123def456ghi789jkl012mno345
client_secret=pqr678stu901vwx234yz567abc890
public_key_id=a1b2c3d4
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDjBABgkqhkiG9w0BBQ0wOzAbBgkqhkiG9w0BBQwwDgQI...=\n-----END ENCRYPTED PRIVATE KEY-----\n
passphrase=1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p
enterprise_id=123456789
supported_mimetypes=application/pdf

Skript:

url=file.url
title=file.name
content=file.contents
mimetype=file.mimetype
filetype=file.filetype
filename=file.name
content_length=file.size
created=file.created_at
last_modified=file.modified_at

Fehlerbehebung

Authentifizierungsfehler

Symptom: Authentication failed oder Invalid grant

Zu überprüfen:

  1. Überprüfen Sie, ob client_id und client_secret korrekt sind

  2. Überprüfen Sie, ob der private Schlüssel korrekt kopiert wurde (Zeilenumbrüche als \n)

  3. Überprüfen Sie, ob die Passphrase korrekt ist

  4. Überprüfen Sie, ob die App in der Box Admin-Konsole genehmigt wurde

  5. Überprüfen Sie, ob die enterprise_id korrekt ist

Formatfehler beim privaten Schlüssel

Symptom: Invalid private key format

Lösung:

Überprüfen Sie, ob die Zeilenumbrüche im privaten Schlüssel korrekt in \n umgewandelt wurden:

# Korrektes Format
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----\nMIIFDj...\n-----END ENCRYPTED PRIVATE KEY-----\n

# Falsches Format (enthält tatsächliche Zeilenumbrüche)
private_key=-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDj...
-----END ENCRYPTED PRIVATE KEY-----

Keine Dateien abrufbar

Symptom: Crawling erfolgreich, aber 0 Dateien

Zu überprüfen:

  1. Überprüfen Sie, ob „Read all files and folders“ in den Application Scopes aktiviert ist

  2. Überprüfen Sie, ob der App Access Level auf „App + Enterprise Access“ gesetzt ist

  3. Überprüfen Sie, ob tatsächlich Dateien im Box-Speicher existieren

  4. Überprüfen Sie, ob das Service-Konto die entsprechenden Berechtigungen hat

Bei großen Dateimengen

Symptom: Crawling dauert lange oder Timeout

Lösung:

Teilen Sie die Verarbeitung in den Datenspeicher-Einstellungen auf:

  1. Passen Sie das Crawl-Intervall an

  2. Teilen Sie in mehrere Datenspeicher auf (z.B. nach Ordner)

  3. Erhöhen Sie die Anzahl der Threads mit dem Parameter number_of_threads

  4. Verteilen Sie die Last über die Zeitplaneinstellungen

Berechtigungen und Zugriffskontrolle

Box-Kollaborationsberechtigungen abbilden

Über das BoxFileAPI-Objekt, das vom Feld file.api bereitgestellt wird, können Box-Kollaborationsinformationen auf Fess-Suchrollen abgebildet werden. file.api.collaborationRoles gibt eine Liste von Suchrollen zurück, die den Benutzern und Gruppen entsprechen, die auf die Datei zugreifen können.

Berechtigungen im Skript setzen:

url=file.url
title=file.name
content=file.contents
role=file.api.collaborationRoles
mimetype=file.mimetype
filename=file.name
created=file.created_at
last_modified=file.modified_at

Bemerkung

file.api.collaborationRoles ruft für jede Datei Kollaborationsinformationen ab, was die Anzahl der Box-API-Aufrufe erhöht und das Crawling verlangsamen kann.

Um allen Dateien eine feste Rolle zuzuweisen, geben Sie diese wie folgt an:

role="{role}box-users"

Weiterführende Informationen