Simple Sword Server
1.0.0
Autor: Richard Jones
Der Simple Sword Server muss Folgendes verwenden:
1/ Es handelt sich um eine Serverbibliothek, die Python-Server verwenden können, um SWORDv2-kompatibel zu sein. 2/ Es handelt sich um einen eigenständigen Server, der eine Referenzimplementierung der SWORD 2.0-Spezifikation bereitstellt
SSS hängt von web.py und lxml ab, daher müssen Sie beide easy_installieren, bevor Sie fortfahren. Damit lxml installiert werden kann, müssen Sie libxml2 und libxslt1.1 installiert haben.
SSS verfügt über ein Konfigurationsobjekt, das geändert werden kann, um einige Aspekte seines Verhaltens zu ändern. Öffnen Sie sss.py zum Bearbeiten und suchen Sie das Konfigurationsobjekt. Jede der Ihnen zur Verfügung stehenden Optionen wird inline dokumentiert.
Wenn Sie dies mithilfe des Schnellstarts unten ausführen, können Sie die Konfiguration unverändert lassen und alles sollte funktionieren. Wenn Sie SSS mit web.py unter Apache bereitstellen, müssen Sie das Konfigurationsobjekt von CherryPyConfiguration in ApacheConfiguration ändern, was am Ende der Datei erfolgen kann.
SSS bietet ein Objektmodell, zwei Web-API-Implementierungen (für web.py und pylons) und eine zu implementierende Serverschnittstelle, um die SWORD-API an den zugrunde liegenden Server zu binden.
Die vom Server zu implementierende Schnittstelle ist sss.SwordServer. Dies kann dann in der Konfigurationsdatei sss.conf.json konfiguriert werden, die von SSS zum Laden als Implementierung des Servers verwendet wird.
Die Web.py-API befindet sich in sss.webpy und kann nur eigenständig ausgeführt werden. Dies ist die empfohlene Verwendung von SSS für die Referenzimplementierung (siehe unten).
Die Pylons-API befindet sich in sss.pylons_sword_controller und kann sehr einfach in ein Pylons-Projekt importiert werden. Sie sollten in Ihrem Pylons-Projekt einen neuen Controller erstellen und den Körper dieses Controllers einfach so gestalten:
from sss.pylons_sword_controller import SwordController __controller__ = "SwordController"
Wenn es als Referenzimplementierung ausgeführt wird, reagiert SSS auf Anfragen, als wäre es ein echter SWORD 2.0-Server, obwohl es sich unter der Haube um einen einfachen Dateispeicher handelt, der nur eine minimale Verarbeitung der Inhalte durchführt, mit denen er arbeitet.
HINWEIS: Die standardmäßige Verwendung von CherryPy unterstützt HTTP 1.1 nicht (aufgrund eines Fehlers), daher müssen Sie Anfragen mit HTTP 1.0 stellen. Dies ist ein Ärgernis, daher wird für andere Verwendungszwecke als die Verwendung von CURL empfohlen, SSS hinter Apache auszuführen, wie weiter unten beschrieben ...
Um SSS mit CherryPy zu starten, platzieren Sie sss.py in einem geeigneten eigenen Verzeichnis und starten Sie es mit
python sss.py
Dadurch wird der Webserver gestartet
http://localhost:8080/
Beachten Sie, dass SSS automatisch einen Datenspeicher in dem Verzeichnis erstellt, in dem sich die Datei sss.py befindet. Dies sollte daher in einem geeigneten Verzeichnis erfolgen. Um den Server auf einem alternativen Port (z. B. 8443) zu starten, starten Sie ihn mit
python sss.py 8443
Um HTTP 1.1-Unterstützung zu erhalten, ist es notwendig, SSS unter Apache bereitzustellen (CherryPy unterstützt HTTP 1.1 derzeit aufgrund eines Fehlers nicht).
Dazu können Sie den Anweisungen folgen unter:
http://webpy.org/cookbook/mod_wsgi-apache
Wenn Sie Ihre httpd.conf-Datei einrichten, müssen Sie die Konfiguration wie folgt einrichten, um Datei-Uploads die Verwendung von Transfer-Encoding: chunked zu ermöglichen und sicherzustellen, dass Autorisierungsanmeldeinformationen weitergeleitet werden:
LoadModule wsgi_module /usr/lib/apache2/modules/mod_wsgi.so WSGIScriptAlias /sss /path/to/SSS/sss.py WSGIPassAuthorization On Alias /sss/static /path/to/SSS/static/ AddType text/html .py <Directory /path/to/SSS/> WSGIChunkedRequest On Order deny,allow Allow from all </Directory>
Beachten Sie, dass dadurch ein expliziter Speicherort für das wsgi_module festgelegt wird (erforderlich für Ubuntu, YMMV auf anderen Plattformen) und WSGIChunkedRequest dem richtigen Kontext hinzugefügt wird.
In diesem Abschnitt wird eine Reihe von CURL-Anfragen beschrieben, die jeden Teil des SWORD-Webdienstes nutzen
Beachten Sie, dass wir für POST- und PUT-Anfragen HTTP 1.0 für die Curl-Anfragen verwenden. Dies liegt daran, dass der CherryPy-Webserver, unter dem SSS läuft, nativ nicht richtig auf diese Anfragen reagiert (obwohl die Funktionalität des Servers dadurch nicht beeinträchtigt wird). Sie werden möglicherweise feststellen, dass die Programmierung gegen das SSS die explizite Verwendung von HTTP 1.0 erfordert – dies sollte NICHT als Voraussetzung für SWORD 2.0 angesehen werden.
###Authentifizierung
Um die verschiedenen Authentifizierungsergebnisse anzuzeigen, versuchen Sie die folgenden Anforderungen für das Dienstdokument. Standardmäßig verfügt SSS über die folgenden Benutzerdetails:
Benutzer: Schwert
Passwort: Schwert
Im Namen von: Obo
curl -i http://sword:sword@localhost:8080/sd-uri
Erfolgreiche Authentifizierung ohne einen On-Behalf-Of-Benutzer
curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri
Erfolgreiche Authentifizierung mit einem On-Behalf-Of-Benutzer
curl -i http://localhost:8080/sd-uri
Keine Basic Auth-Anmeldeinformationen angegeben, 401 Nicht autorisierte Antwort
curl -i http://sword:drows@localhost:8080/sd-uri
Falsches Passwort, 401 nicht autorisierte Antwort
curl -i http://drows:sword@localhost:8080/sd-uri
Falscher Benutzer, 401 nicht autorisierte Antwort
curl -i -H "X-On-Behalf-Of: bob" http://sword:sword@localhost:8080/sd-uri
Korrekter Benutzer, aber ungültiger „Im Namen von“-Benutzer, 401 nicht autorisierte Antwort
Alle nachfolgenden Anfragen können mit einem X-On-Behalf-Of-Header erfolgen; Es werden keine weiteren Beispiele aufgeführt
###Holen Sie sich das Servicedokument
HTTP: GET auf SD-URI
curl -i http://sword:sword@localhost:8080/sd-uri
Dadurch wird das Servicedokument mit der konfigurierten Anzahl aufgelisteter Sammlungen zurückgegeben
###Hinterlegen Sie einige neue Inhalte
HTTP: POST auf Col-URI
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" sword:sword@[Col-URI]
Dadurch wird die Datei „example.zip“ mit dem Dateinamen „example.zip“ im Col-URI gepostet und angegeben, dass es sich um eine ZIP-Datei handelt. Ohne den X-Packaging-Header wird dies als Standard-SWORD-Paket interpretiert. Col-URI sollte dem Servicedokument entnommen werden.
Dies sollte den HTTP-Status „201 erstellt“ und eine Einzahlungsbestätigung zurückgeben
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-In-Progress: true" sword:sword@[Col-URI]
Dies sollte einen HTTP-Status von 202 Akzeptiert und eine Einzahlungsbestätigung zurückgeben
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Col-URI]
Dies imitiert eine Atom-Multipart-Einzahlung und erstellt zwei Elemente im Container: atom.xml und example.xml (mit dem Präfix des aktuellen Zeitstempels). Dies sollte den HTTP-Status „201 erstellt“ und eine Einzahlungsbestätigung zurückgeben. Sie können hinzufügen
-H "X-In-Progress: true" to get a 202 Accepted back instead, as above. curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP" sword:sword@[Col-URI]
Dies ist ein Beispiel, bei dem ein anderes Paketformat für example.zip verwendet wird. Im Moment lässt der Ingest-Packager in SSS dieses Paket einfach so, wie es ist, ohne zu versuchen, es zu entpacken
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "Content-MD5: 2b25f82ba67284461d4a481d7a06dd28" sword:sword[Col-URI]
Dies ist ein Beispiel, in dem wir die korrekte MD5-Prüfsumme für das Element bereitstellen, nur um zu zeigen, dass dies mit oder ohne Prüfsumme funktioniert. Informationen zur Bereitstellung falscher Prüfsummen finden Sie im folgenden Abschnitt zu Fehlern.
###Listen Sie den Inhalt einer Sammlung auf
HTTP: GET auf Col-URI
curl -i sword:sword@[Col-URI]
Dadurch wird ein Atom-Feed zurückgegeben, in dem jeder atom:entry auf eine Sammlung in der angegebenen Sammlung verweist. Dies wird nur aus Gründen der Bequemlichkeit implementiert und ist daher kein vollständiger Feed. Stattdessen enthält es lediglich ein atom:link-Element, das den href zum Edit-URI für diese Sammlung enthält
###Erhalten Sie eine Darstellung des Containers (Medienressource)
HTTP: GET auf dem Cont-URI oder EM-URI
curl -i [EM-URI]
Rufen Sie das Standardverbreitungspaket vom Server ab. In diesem Fall füllt Curl den Accept-Header für uns mit „ / “ aus. Dadurch wird eine Anwendungs-/ZIP-Datei mit dem gesamten Inhalt im Container zurückgegeben. Beachten Sie, dass für diese Anfrage keine Authentifizierung erforderlich ist, da SSS dies als Beispiel für die öffentliche Seite des Inhalts modelliert.
FIXME: Diese Methode der Inhaltsverhandlung wird diskutiert, obwohl sie derzeit vom SSS unterstützt wird
curl -i -H "Accept: application/zip;swordpackage=http://www.swordapp.org/package/default" [EM-URI]
Fordern Sie ausdrücklich eine ZIP-Datei im Standard-Sword-Paketformat an (bei dem es sich übrigens um eine einfache ZIP-Datei handelt).
curl -i -H "Accept: application/zip" [EM-URI]
Fordern Sie ausdrücklich eine gewöhnliche ZIP-Datei des Inhalts an (die sich zufällig nicht vom Standard-Sword-Paket unterscheidet).
curl -i -H "Accept: text/html" [EM-URI]
Fordern Sie explizit die HTML-Darstellung der Medienressource an. Dadurch wird ein HTTP-Header „302 Found“ mit einem Location-Header zurückgegeben, der auf die HTML-Darstellung verweist
curl -i -H "Accept: application/vnd+msword" [EM-URI]
Generieren Sie den Fehler „415 Nicht unterstützter Medientyp“.
###Überschreiben Sie die vorhandene Medienressource mit einer neuen
HTTP: PUT auf EM-URI
curl -i -X PUT --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" sword:sword@[EM-URI]
Dadurch werden alle vorhandenen Inhalte in dem mit dem EM-URI identifizierten Container durch die angehängte Datei example.zip ersetzt. Das Paketformat wird als Standardschwertpaket interpretiert. Es werden eine 201 erstellte Quittung und eine Einzahlungsquittung zurückgegeben
curl -i -X PUT --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-In-Progress: true" sword:sword@[EM-URI]
Dies führt zu dem gleichen Vorgehen wie oben, gibt jedoch die Fehlermeldung 202 Accepted zurück, die angibt, dass das Update auf dem Server akzeptiert, aber noch nicht verarbeitet wurde (zum Beispiel natürlich; es macht keinen Unterschied, was eigentlich passiert). geschieht auf dem Server).
FIXME: So funktioniert AtomPub nicht, es heißt stattdessen, dass dies einen Wert von 200 zurückgeben sollte – die Entscheidung für SWORD ist diesbezüglich noch nicht entschieden
curl -i -X PUT --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-Suppress-Metadata: true" sword:sword@[EM-URI]
Dies würde das Gleiche tun wie oben, weist den Server jedoch an, die Metadaten des Artikels basierend auf dieser Einzahlung nicht zu aktualisieren. SSS implementiert keine Metadatenaktualisierungen für Standardpakete, die nicht mehrteilig sind, sodass dies keine tatsächlichen Auswirkungen hat, es sich jedoch um eine gültige Anfrage handelt.
curl -i -X PUT --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP" sword:sword@[EM-URI]
Ein Beispiel wie oben, jedoch mit übergebenem X-Packaging-Header.
###Löschen Sie den Inhalt, aber nicht den Container
HTTP: DELETE auf EM-URI
curl -i -X DELETE sword:sword@[EM-URI]
Dadurch wird der gesamte Inhalt aus dem Speicher gelöscht, jedoch nicht der Container selbst, und es werden ein „200 OK“ und ein Einzahlungsbeleg zurückgegeben
###Erhalten Sie eine Darstellung des Containers
HTTP: GET auf Edit-URI
curl -i sword:sword@[Edit-URI]
Dadurch wird der Edit-URI in seinem Standardformat abgerufen, das eine Kopie des Einzahlungsbelegs ist – ein Atom-Eingabedokument
curl -i -H "Accept: application/rdf+xml" sword:sword@[Edit-URI]
Dadurch erhalten wir die reine RDF/XML-Anweisung aus dem Repository
curl -i -H "Accept: application/atom+xml;type=entry" sword:sword@[Edit-URI]
Dadurch wird der Edit-URI explizit in seiner Atom-Eintragsform angefordert, die mit dem Standardformat übereinstimmt
###Aktualisieren Sie einen Container, indem Sie neuen Inhalt zum vorhandenen Inhalt hinzufügen
HTTP: POST auf Edit-URI
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" sword:sword@[Edit-URI]
Dadurch wird die Datei „example.zip“ zum Server hinzugefügt (beachten Sie, dass die Content-Disposition ihr denselben Namen gibt – SSS lokalisiert die Namen beim Empfang, um ein Überschreiben vorhandener Dateien zu vermeiden), ohne dass der vorhandene Inhalt entfernt wird. Dadurch werden ein 201 „Erstellt“ (oder, wenn Sie den X-In-Progress-Header hinzufügen, ein 202 „Akzeptiert“) und der Einzahlungsbeleg zurückgegeben.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Edit-URI]
Dies imitiert eine Atom-Multipart-Einzahlung und erstellt zwei Elemente im Container: atom.xml und example.xml (mit dem Präfix des aktuellen Zeitstempels). Die Datei „atom.xml“ überschreibt in diesem Fall jede vorhandene Datei „atom.xml“, während die Datei „example.zip“ lediglich unter einem lokalisierten Namen hinzugefügt wird. Dies sollte den HTTP-Status „201 erstellt“ und eine Einzahlungsbestätigung zurückgeben. Sie können -H „X-In-Progress: true“ hinzufügen, um stattdessen wie oben „202 Accepted“ zurückzuerhalten.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" -H "X-Suppress-Metadata: true" sword:sword@[Edit-URI]
Diese Version der Anfrage mit dem gesetzten Header
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-Packaging: http://purl.org/net/sword/package/METSDSpaceSIP" sword:sword@[Edit-URI]
###Löschen Sie den Container und seinen gesamten Inhalt
HTTP: DELETE bei Edit-URI
curl -i -X DELETE sword:sword@[Edit-URI]
Dadurch wird der gesamte Inhalt aus dem Container entfernt, gefolgt vom Container selbst. Es wird eine 204 No Content-Antwort ohne Antworttext zurückgegeben.
###Fehler generieren
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-Packaging: http://purl.org/net/sword/package/error" sword:sword[Col-URI]
Erzeugt eine ErrorContent-Fehlerantwort beim Hinterlegen eines Pakets, dessen Pakettyp nicht mit dem X-Packaging-Header übereinstimmt
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "Content-MD5: 1234567890" sword:sword[Col-URI]
Generieren Sie einen Fehler für eine Nichtübereinstimmung zwischen der Prüfsumme und dem bereitgestellten Prüfsummen-Header, was zu einem Fehler „412 Vorbedingung fehlgeschlagen“ führt.
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" -H "X-In-Progress: whatever" sword:sword[Col-URI]
Generieren Sie einen Bad Request-Fehler, indem Sie einen unzulässigen Wert an X-In-Progress übergeben, was zu einer 400 Bad Request-Antwort führt
