zplCloud Blog
Lokale MongoDB per zplCloud-CLI als Label-Datenquelle anbinden
Filter werden zu nativen Query-Dokumenten, ausgeführt vom Agent in deinem Netz. Der Connection-String bleibt auf deiner Maschine.
Kein Export, keine Kopie deiner Collection in der Cloud
Produktdaten, Auftragspositionen, Seriennummern - wenn das alles schon in MongoDB liegt, ist ein CSV-Export nur dafür, dass ein Label es drucken kann, reiner Overhead. Und der Export ist in dem Moment veraltet, in dem er geschrieben wird.
Der zplCloud-Datenhub bindet die Collection direkt an. Ein CLI-Agent in deinem Netz hält den Connection-String, die Plattform beschreibt die Abfrage, der Agent liefert nur die passenden Dokumente zurück. Die Datenbank bleibt aus dem Internet unerreichbar.
Architektur
zplcloud proxy hält eine ausgehende TLS-Verbindung zu api.zplcloud.com. Auf deiner Seite lauscht nichts, also kein eingehender Port und keine Firewall-Ausnahme. Query, Sortierung und Paging werden heruntergedrückt: Der Agent baut eine echte MongoDB-Abfrage und ruft Find(filter).Sort(…).Skip(n).Limit(m). Die Collection wird nie heruntergeladen.
Schritt 1 - Agent mit deiner MongoDB starten
# Mehrere --mongo-Flags sind erlaubt; der NAME ist das, was du in der Plattform auswählst.
zplcloud proxy --agent "Lager" \
--mongo LOCAL="mongodb://admin:…@127.0.0.1:27017/products" \
--mongo PROD="mongodb://admin:…@mongo.internal.lan:27017/erp"
Der Connection-String muss den Datenbanknamen enthalten - der Teil nach dem Host, …:27017/products. Ohne ihn hat der Agent einen Server, aber keine Datenbank zum Abfragen.
Secrets gehören nicht in die Shell-History:
$env:ZPLCLOUD_MONGO_LOCAL_CONNECTION = "mongodb://admin:…@127.0.0.1:27017/products"
zplcloud proxy --agent "Lager"
Der Banner bestätigt, was registriert wurde: MongoDB servers: LOCAL, PROD. Authentifizierung gegenüber der Plattform per --api-key <key> oder ZPLCLOUD_API_KEY; dauerhaft mit --service-install (systemd unter Linux/Raspberry Pi, geplante Aufgabe unter Windows) oder per ZPLCLOUD_MONGO_LOCAL_CONNECTION in docker-compose.agent.yml.
Gib dem Agent einen lesenden Benutzer, beschränkt auf die Datenbank, die er braucht. Der Agent führt als dieser Benutzer aus - MongoDBs eigenes Rollenmodell ist die Rechtegrenze.
Schritt 2 - Datenquelle anlegen
Unter Datenquellen erscheint der Agent als Remote SQL Server mit einem Chip je MongoDB-Instanz. Ein Klick füllt das Formular vor.
| Feld | Wert |
|---|---|
| Name | Lager-Artikel |
| Typ | MongoDB |
| Server | LOCAL (der Name aus --mongo LOCAL=…) |
| Collection | products |
Test pingt die Instanz und liefert server · datenbank. Felder liest ein Beispieldokument und listet die Feldnamen mit ihren BSON-Typen.
Die Felderkennung arbeitet mit einer Stichprobe - in einem schemalosen Store ist das relevant: Fehlt ein Feld in den ersten Dokumenten und taucht erst später auf, steht es nicht in der Liste. Wenn du weißt, dass es existiert, trage es im Binding von Hand ein.
Schritt 3 - wie ein Filter ausgeführt wird
Die Filterzeile aus Abfragen - Spalte, Operator, Wert - wird in ein MongoDB-Filterdokument übersetzt und vom Agent ausgeführt:
| Operator in der UI | MongoDB |
|---|---|
enthält | { ean: { $regex: "40063813" } } |
beginnt mit | { ean: { $regex: "^40063813" } } |
= | { ean: "40063813" } |
> / < | { price: { $gt: 10 } } / { $lt: … } |
Zwei Konsequenzen, die man klar aussprechen sollte:
- Es gibt keine Injection-Fläche. Ein MongoDB-Filter ist ein BSON-Dokument - Daten, kein String, der als Code geparst wird. Ein Wert mit
$oder{}bleibt ein Wert. $regexohne Anker kann keinen Index nutzen.enthältist auf einer großen Collection ein Full Scan.beginnt miterzeugt^…, das ein normaler Index auf dem Feld bedienen kann. Bei großen Collections alsobeginnt mitbevorzugen.
Die harten Grenzen (aus dem Agent-Quellcode)
| Grenze | Wert |
|---|---|
| Zeilen pro Request | 1000 - limit wird begrenzt, Default ist 100 |
| Server-Selection-Timeout | 15 s - ein nicht erreichbares Replica Set scheitert hier, nicht erst nach Minuten |
| Ausgeführte Operation | nur lesend: Find mit Sortierung, Skip und Limit |
Größere Ergebnismengen werden geblättert: Die Plattform fordert Seite für Seite mit wachsendem Skip an, jede auf 1000 Dokumente begrenzt. Ein Batch-Druck mit 10.000 Labels hält deshalb auf keiner Seite mehr als eine Seite im Speicher.
Zu beachten: Skip mit großem Offset lässt MongoDB die übersprungenen Dokumente durchlaufen. Bei Katalogen im sechsstelligen Bereich hält ein indiziertes Sortierfeld das billig - ein unindiziertes nicht.
Schritt 4 - im Designer und in Print Views nutzen
- Designer → Tab Testdaten → Datenquelle: Datenquelle wählen, Laden drücken - jedes Binding rendert mit echten Dokumenten. Feldlängen, fehlende Werte und Encoding-Probleme zeigen sich hier statt auf der Etikettenrolle.
- Print Views → Konfiguration → Datenquelle (Datenhub): Vorschau und Druck nutzen die Live-Query. Die Bedienung merkt nie, dass eine MongoDB dahintersteht.
Fehlerbilder
| Symptom | Ursache |
|---|---|
| Agent läuft, kein Chip im Datenhub | --mongo-Name fehlt, oder der API-Key gehört zu einem anderen Workspace |
Test scheitert nach ~15 s | Server-Selection-Timeout - Host vom Agent-Rechner nicht erreichbar, falscher Port, oder ein Replica Set, dessen Member Namen melden, die der Agent nicht auflösen kann |
Test scheitert sofort mit Auth-Fehler | Benutzer/Passwort falsch, oder die Auth-Datenbank weicht von der Daten-Datenbank ab (?authSource=admin) |
Felder übersieht ein Feld | das Beispieldokument enthält es nicht - schemalose Collections brauchen eine repräsentative Stichprobe |
| Filter liefert nichts, obwohl der Wert sichtbar ist | Typ-Mismatch: numerisches Feld gegen einen String verglichen. Typ in der Feldliste prüfen |
Tarif
Der Datenhub (MongoDB- und SQL-Server-Datenquellen über den CLI-Agent) gehört zum Pro-Tarif. Siehe Preisseite.