Export und Import

Export

In der Pflegeanwendung gibt es für einen ganzen Namensraum und für eine einzelne API die Schaltfläche Export. Sie liefert ein ZIP-Archiv mit allen zugehörigen APIs und Datensätzen. Da es auch sämtliche Mediendateien enthält, kann es recht groß werden.

Der Export ist ein einfacher HTTP GET:

GET /data/<Namensraum>/_export/<Muster>

• Namensraum: aus diesem Namensraum wird exportiert.
• Muster: ein regulärer Ausdruck, der die zu exportierenden APIs festlegt. Er muss auf den ganzen Namen passen.

Aufruf	Exportiert
/data/tutorial/_export/api1	die API api1
/data/tutorial/_export/.*	alle APIs im Namensraum tutorial
/data/tutorial/_export/(api\d+|languages)	alle APIs, deren Name mit api beginnt und nur mit Ziffern weitergeht, sowie die API languages

curl -u "$USER" -o tutorial.zip "$CMS/data/tutorial/_export/.*"

Für die Projektansicht gibt es außerdem einen Export nach Projekt und Anwendung (siehe Einordnung). Er kann APIs aus verschiedenen Namensräumen umfassen:

Aufruf	Exportiert
/projects/_export/<Projekt>	alle APIs des Projekts
/projects/_export/<Projekt>*!*<Anwendung>	nur die APIs einer Anwendung des Projekts

Exportiert wird jeweils nur, worauf das Konto Leserecht hat.

Import

Für den Import wird ein per Export erstelltes ZIP-Archiv mit HTTP POST an /import gesendet (Content-Type: application/zip). In der Pflegeanwendung gibt es dafür die Schaltfläche Import auf der Startseite.

Eine Auswahl einzelner APIs aus dem Archiv ist nicht vorgesehen. Der Vorgang wird über URL-Parameter gesteuert, z. B. /import?execute&insertOnly:

Parameter	Wirkung
execute	Ohne diesen Parameter wird das Archiv nur auf Verwendbarkeit geprüft, es werden keine Daten verändert.
insertOnly	Hat eine API bereits Datensätze, werden nur bisher unbekannte Datensätze (_id) übernommen. Vorhandene werden nie verändert.
allowDataLoss	Vorhandene Datensätze werden vor dem Einspielen entfernt. Die API entspricht danach exakt dem Stand im Archiv.
skipProtectedApis	APIs, in die das Konto keine Datensätze einspielen darf, werden übersprungen.
skipProtectedNamespaces	Namensräume, in denen das Konto keine APIs anlegen oder ändern darf, werden übersprungen.

# Erst prüfen
curl -X POST -u "$USER" -H 'Content-Type: application/zip' --data-binary @tutorial.zip "$CMS/import"

# Dann ausführen, nur neue Datensätze übernehmen
curl -X POST -u "$USER" -H 'Content-Type: application/zip' --data-binary @tutorial.zip "$CMS/import?execute&insertOnly"

Die Parameter sollten mit Sorgfalt gewählt und nicht unnötig gesetzt werden, execute natürlich ausgenommen. Ein unbedachtes allowDataLoss kann zum unwiederbringlichen Verlust vorhandener Daten führen.

Ablauf

1. Die Beschreibung aller betroffenen APIs wird auf den Stand des Archivs gebracht. Vorhandene Datensätze können dadurch ungültig werden, eine Migration findet nicht statt. Wenn möglich, wird die existierende API dafür gelöscht, nämlich wenn sie noch keine Datensätze hat oder allowDataLoss gesetzt ist.
2. Hat eine API Datensätze und sind weder allowDataLoss noch insertOnly gesetzt, bricht der Vorgang ab.
3. Darf das Konto im Namensraum keine APIs anlegen oder ändern und ist skipProtectedNamespaces nicht gesetzt, bricht der Vorgang ebenfalls mit einem Fehler ab.
4. Alle Datensätze und Dateien des Archivs werden eingespielt. Bereits vorhandene identische Datensätze bleiben unverändert. Das kommt nur bei insertOnly vor, sonst wurde die API samt Daten vorher gelöscht.
5. Darf das Konto in einer API keine Datensätze anlegen, ändern oder löschen und ist skipProtectedApis nicht gesetzt, endet der Vorgang mit einer Fehlermeldung.

Die Antwort beschreibt als JSON das Ergebnis. Die Pflegeanwendung zeigt es für jede API im Archiv an, zusammen mit dem Gesamterfolg. Im Dialog sind die Parameter noch einmal ausführlicher erklärt.

Typischer Einsatz

Ein CMS, das während der Entwicklungsphase im Internet läuft, wird zur Eröffnung in das lokale CMS der Ausstellung übertragen (siehe Wann kommen die Daten?): Export des Namensraums bzw. Projekts im einen CMS, Import mit execute im anderen.