Datenquellen

Über Datenquellen bindest du bestehende Inhalte automatisiert in deine Wissensbasis ein – per Website-Crawler, Datei-Upload, Webhooks, OpenAPI-Spezifikation, HelpSpace, WordPress oder MySQL/Postgres.

Gemeinsame Einstellungen

Für alle Datenquellen außer Datei-Upload (sofern du kein Dokument verlinkst) kannst du einen Zeitplan (Schedule) festlegen, wann diese Datenquelle deine Inhalte im Hintergrund aktualisieren soll.

Name
Zeitplan (Schedule): Gib einen gültigen Cron-Ausdruck ein. Basierend auf dem Zeitplan wird der Webcrawler automatisch ausgeführt und aktualisiert bestehende oder erstellt neue Nodes. Nutze einen Dienst wie https://crontab.guru/, um einen Cron-Ausdruck für deine Datenquelle zu erstellen. Bitte beachte, dass der Mindestabstand zwischen Ausführungen 60 Minuten betragen muss.
Richtlinie für nicht verfügbare Quellen (Unavailable Source Policy): Wähle, wie mit nicht verfügbaren Quellen/URLs während der Ausführung umgegangen werden soll. Ignore behält bestehende Daten bei, während Delete Unavailable Seiten entfernt, die nicht mehr erreichbar sind. Wir prüfen den HTTP-Statuscode aller Seiten: Liegt dieser bei 404 (Not Found), 410 (Gone), 308 (Permanent Redirect) oder 301 (Moved Permanently), werden die Nodes für diese Seiten gelöscht.

Du kannst einen Datenquellen-Durchlauf abbrechen, während er ausgeführt wird. Das Abbrechen eines Website-Crawler-Durchlaufs stoppt auch den eigentlichen Webcrawler, sodass keine weiteren Seiten verarbeitet werden.

Website-Crawler

Der Website-Crawler beginnt mit den Start-URLs, findet Links zu weiteren Seiten und crawlt diese rekursiv, solange sich deren URL unterhalb der Start-URL befindet. Wenn du beispielsweise die Start-URL https://example.com/blog/ eingibst, crawlt der Crawler Seiten wie https://example.com/blog/article-1 oder https://example.com/blog/section/article-2, überspringt jedoch Seiten wie https://example.com/docs/something-else. Mit der Option Dokumente aufteilen (Split Documents) versuchen wir, die semantische Struktur der Website anhand ihrer Überschriften zu erkennen und mehrere Nodes für dich zu erstellen. Das Ergebnis hängt von der semantischen Qualität deiner Website ab.

Konfigurationsoptionen

Dokumente aufteilen (Split documents): Wir können versuchen, die semantische Struktur deiner Website zu erkennen und anhand der HTML-Überschriften (h1, h2 usw.) deiner Seite mehrere Nodes für dich zu erstellen. Diese Einstellung ist besonders beim Crawlen technischer Dokumentationen oder langer Textseiten hilfreich.
Crawler-Typ (Crawler Type): Wähle zwischen Adaptive (Standard), Cheerio und Playwright. Wir empfehlen zu Beginn den Typ Adaptive, da dieser JavaScript verarbeiten kann und dynamisch zwischen HTTP-Requests und JavaScript-Ausführung wechselt.
Akteur (Actor): Für Nutzer steht ausschließlich der Website Content Crawler zur Verfügung. Für spezielle Anwendungsfälle können wir einen individuellen Crawler entwickeln.
URL-Globs einschließen (Include URL Globs): Glob-Patterns passend zu URLs von Seiten, die in das Crawling einbezogen werden sollen. Das Setzen dieser Option deaktiviert das standardmäßige Scoping auf Basis der Start-URLs. Beachte, dass dies nur Links betrifft, die auf Seiten gefunden werden.

Beispiel: start_urls: ["example.com/test"], include_url_globs = ["example.com/test/**", "example.com/test-2/**"] In diesem Fall werden auch URLs in die Ergebnisse aufgenommen, die auf example.com/test gefunden werden und mit example.com/test-2/ beginnen. Dies ist vorteilhaft, wenn die Struktur deiner Website nicht streng hierarchisch ist.
URL-Globs ausschließen (Exclude URL Globs): Glob-Patterns passend zu URLs von Seiten, die vom Crawling ausgeschlossen werden sollen. Beachte, dass dies nur auf Seiten gefundene Links betrifft, nicht jedoch die Start-URLs, die immer gecrawlt werden. Beispiel: start_urls: ["example.com"], exclude_url_globs = ["example.com/impressum"] Hier wird die spezifische URL example.com/impressum aus den Ergebnissen ausgeschlossen, obwohl sie gemäß den start_urls hineinpassen würde.
Fehler ignorieren (Ignore Errors): Wähle dies aus, wenn dein Sprachcode nicht korrekt gesetzt ist und du Fehler (Statuscode, Sprachcode usw.) ignorieren möchtest.
HTML-Elemente entfernen (Remove HTML Elements): Definiere HTML-Elemente über ihre CSS-Selektoren, die von der Verarbeitung ausgeschlossen werden sollen. Wir haben die gängigsten Elemente wie nav, header und footer vorkonfiguriert. Muss als kommagetrennte Liste angegeben werden. Benutzerdefinierte Attribute wie div[my-custom-attribute="hello"] dürfen nicht escaped werden, da dies vom System übernommen wird. Du kannst die Browser-Entwicklertools und die Browser-Konsole mit der Methode document.querySelectorAll() nutzen, um die CSS-Selektoren zu ermitteln. Sonderzeichen müssen hier nicht escaped werden.
Filter: Definiere Filterkriterien für Seiten-Metadaten. Derzeit unterstützen wir das Filtern von Feldern: modified_time, published_time anhand eines max_age_days-Werts (z. B. Seiten, die vor mehr als einem Jahr aktualisiert wurden).
Benutzerdefinierte Tags (Custom Tags): Liste von Tags, die für jedes Suchergebnis bei der Suche über das Such-Interface oder den Navigator angezeigt werden. Alle Webseiten, die über diese Datenquelle gecrawlt werden, erhalten ein tags-Array innerhalb von custom_metadata (d. h. die Tags werden von allen Webseiten dieser Datenquelle geteilt).

Datei-Upload

Wir unterstützen eine Vielzahl von Dateiformaten, darunter PDF, CSV, XLSX, DOCX und TXT. Für PDFs kannst du außerdem eine feste URL angeben, die in regelmäßigen Intervallen gecrawlt wird. Die Sprache bzw. die Locale der Dokumente wird automatisch erkannt. Die maximale Upload-Größe beträgt 20 MB.

Webhooks

branchly unterstützt Webhooks, sodass du Elemente der Wissensbasis (z. B. Artikel, Webseiten) direkt aus deinem System (z. B. CMS, Shopsystem oder Datenbank) auf unsere Plattform übertragen (pushen) kannst.

Daten-Updates pushen: Anstatt dass branchly Daten von deiner API abruft (Pull), sendet dein System Webhook-Events für Erstellungs-, Aktualisierungs- oder Löschvorgänge, um deine Daten synchron zu halten.
API-Schlüssel: Generiere beim Einrichten einer Webhook-Datenquelle einen API-Schlüssel. Hinweis: Der API-Schlüssel wird nur einmal angezeigt – speichere ihn sicher ab. Du kannst den Schlüssel jederzeit neu generieren; der alte Schlüssel verliert dann seine Gültigkeit.
Öffentliche Dokumentation: Für die OpenAPI-Spezifikation, erforderliche Payload-Attribute und weitere technische Details zur Nutzung von Webhooks siehe: https://api.branchly.io/public/docs#/

Du kannst unsere Vorlagen-Mapping-Funktion (Template Mapping) nutzen, um deine Webhook-Payload in das Schema zu formatieren, das die branchly-Anwendung erwartet:

Datenvorlagen-Mapping (Data Template Mapping): Um deine API-Antworten an die Struktur unserer Wissensbasis anzupassen, verwende die mustache-Template-Syntax. Mustache ist eine weit verbreitete, logikfreie Template-Syntax. Weitere Informationen zu Mustache findest du hier. Das Mapping für die Parameter title, text und source ist erforderlich. Der Wert von source sollte eindeutig und vorzugsweise eine gültige URL sein.

OpenAPI-Spezifikation

Wir bieten die Möglichkeit, deine Daten mithilfe der OpenAPI-Spezifikation direkt von einer API abzurufen. OpenAPI ist ein weit verbreitetes Format für den Austausch von API-Informationen, das häufig zur Code-Generierung von Clients genutzt wird. Weitere Details zur OpenAPI-Spezifikation findest du hier.

Konfigurationsparameter

OpenAPI-Spezifikation: Füge deine OpenAPI-Spezifikation im JSON-Format in das dafür vorgesehene Feld ein.
Operation ID: Gib eine operationId an, um den aufzurufenden Endpunkt zu identifizieren. Diese ID muss eindeutig sein – eine Standardanforderung einer gültigen OpenAPI-Spezifikation.
Zusätzliche Optionen (Extra Options): Für Anfragen verwenden wir Standardwerte. Wenn du Parameter festlegen möchtest, ohne sie in das JSON der OpenAPI-Spezifikation aufzunehmen, füge sie dem Feld extra_options hinzu. Beachte, dass diese zusätzlichen Argumente im schema des definierten Endpunkts existieren müssen.
Datenvorlagen-Mapping (Data Template Mapping): Um deine API-Antworten an die Struktur unserer Wissensbasis anzupassen, verwende die mustache-Template-Syntax. Mustache ist eine weit verbreitet, logikfreie Template-Syntax. Weitere Informationen zu Mustache findest du hier. Das Mapping für die Parameter title, text und source ist erforderlich. Der Wert von source sollte eindeutig und vorzugsweise eine gültige URL sein.
Pfad zum Antwortinhalt (Response Content Path): Dieser optionale Parameter sollte angegeben werden, wenn die Einträge der API-Antwort innerhalb eines Objekts geschachtelt sind. Verwende Keypath- oder Punktnotation, um den Pfad zu definieren.

Derzeit unterstützen wir folgende Szenarien:

Keine Authentifizierung, api_key und Basic Authentication:
- Um api_key zu verwenden, trage deinen API-Schlüssel in das Feld extra_options ein.
- Um Basic Authentication zu nutzen, gib deinen Benutzernamen und dein Passwort im Feld extra_options ein.
Wenn deine API ein Bearer-Token erfordert, das über einen Login-Endpunkt bezogen wird, binde unter Einstellungen → Integrationen eine Token Endpoint-Integration ein und wähle sie als Authentifizierungs-Integration für diese Datenquelle aus. branchly meldet sich mit deinen hinterlegten Anmeldedaten an, cacht das Token und fügt es automatisch ein.
Die API sollte mit dem Statuscode 200 und dem Content-Type application/json antworten.
Das Ergebnis des API-Aufrufs muss ein JSON-Objekt oder ein Array von Objekten sein.
Eine base_url muss entweder in der OpenAPI-Datei unter servers oder als Extra Option angegeben werden (Beispiel: base_url: https://petstore3.swagger.io/api/v3).

Anwendungsbeispiel

Betrachte das folgende JSON-Objekt als deine API-Antwort:

{
  "status": "OK",
  "count": 100,
  "items": [
    {
      "url": "example.com/1234567",
      "id": "1234567",
      "title": "Title of your content",
      "type": "type",
      "texts": {
        "detail": "Detailed text description",
        "summary": "Short summary"
      }
    },
    ... // weitere Einträge mit derselben Struktur
  ]
}

Wenn du Folgendes definierst:

Response Content Path: items
Template Mapping
- Title: The title of this node is: {{title}}
- Text: {{texts.details}}
- Source: {{url}}

Wäre das Ergebnis für den ersten Eintrag im items-Array:

Title: The title of this node is: Title of your content
Text: Detailed text description
Source: example.com/1234567

Das Template wird auf alle Einträge im items-Array angewendet und diese werden als einzelne Nodes in die Wissensbasis geladen.

HelpSpace Docs

In Partnerschaft mit HelpSpace bieten wir eine einfache Anbindung deiner HelpSpace Docs an die branchly-Plattform.

Erforderliche Felder:

Client ID des HelpSpace-Workspaces: Du findest sie unter Settings > Access Token > Client ID
API Token des HelpSpace-Workspaces (Lesezugriff ausreichend): Du findest es unter Settings > Access Token > Access Token
Site ID deiner Docs: Du findest sie unter Docs > Sites > Site ID

WordPress

branchly unterstützt WordPress als Datenquelle, sodass du deine WordPress-Beiträge, -Seiten und individuellen Inhaltstypen direkt in deine Wissensbasis importieren kannst.

Post Types: Wähle aus, welche WordPress-Beitragstypen importiert werden sollen. Standardmäßig sind Standard-Beiträge (Posts) und -Seiten (Pages) ausgewählt. Du kannst jedoch auch beliebige Custom Post Types oder Entitäten (wie Produkte, Portfolio-Einträge oder spezielle Artikel) konfigurieren, die in deinem WordPress definiert sind.
Post Status: Filtere importierte Einträge nach ihrem Beitragsstatus. Standardmäßig ist der Crawler so konfiguriert, dass nur Einträge mit dem Status publish abgerufen werden.
Filter & Einschränkungen: Bestimme präzise, welche Einträge synchronisiert werden. Du kannst Filter wie das Erstellungs- oder Änderungsdatum anwenden (z. B. nur Einträge der letzten 30 Tage synchronisieren), um veraltete Inhalte auszuschließen und die Synchronisationszeit zu optimieren.
URL-Ausschluss (Glob-Patterns): Schließe bestimmte Seiten mit Glob-Patterns wie */lp-*, /page/* oder einer vollständigen URL wie https://example.com/page/ von der Synchronisierung aus. Der Abgleich erfolgt ohne Berücksichtigung der Groß-/Kleinschreibung (case-insensitive) und abschließende Schrägstriche werden normalisiert, sodass ein Pattern mit oder ohne abschließenden Schrägstrich greift. Patterns können vollständige URLs (inklusive Schema und Host), Website-Pfade (z. B. /page/*) oder Slug-Fragmente (z. B. lp-*) sein. Ausgeschlossene URLs werden bei keiner Synchronisierung in die Wissensbasis importiert.
Sprachen: Beschränke den Import über den Sprachfilter auf Beiträge und Seiten einer bestimmten Sprache. Wenn deine WordPress-Website WPML für mehrsprachige Inhalte verwendet, kannst du in der Konfiguration auch Abfrageparameter (wie ?wpml_language=en) angeben, um Zielsprachen abzurufen.
Seiten-Metadaten (Yoast SEO): Die Integration extrahiert automatisch SEO-Titel, -Beschreibung und Schlüsselwort-Metadaten aus den Yoast-SEO-API-Payloads, sofern das Yoast-SEO-Plugin auf deiner WordPress-Site aktiv ist.
Synchronisierung: Führe Synchronisierungen manuell durch oder richte einen wiederkehrenden Zeitplan mittels Cron-Ausdruck ein.

Custom Website Crawler (nur Enterprise-Abonnement)

Für Enterprise-Kunden bieten wir die Entwicklung eines individuellen Crawlers für deinen spezifischen Anwendungsfall an. Bitte kontaktiere uns für weitere Informationen.

MySQL / Postgres

Diese Funktion wird derzeit nur für ausgewählte Testkunden eingesetzt und kann ausschließlich durch Mitarbeiter von branchly aktiviert werden. Wenn du einen Anwendungsfall hast, bei dem dies hilfreich wäre, kontaktiere uns bitte.