Simple Sword Server
1.0.0
Autor: Richard Jones
El Simple Sword Server tiene que usar:
1/ Es una biblioteca de servidor para que los servidores Python la utilicen para ser compatibles con SWORDv2 2/ Es un servidor independiente que proporciona una implementación de referencia de la especificación SWORD 2.0
SSS depende de web.py y lxml, por lo que deberá instalar ambos fácilmente antes de continuar. Deberá haber instalado libxml2 y libxslt1.1 para poder instalar lxml.
SSS tiene un objeto de configuración que se puede modificar para cambiar algunos aspectos de su comportamiento. Abra sss.py para editarlo y busque el objeto Configuración; Cada una de las opciones disponibles para usted está documentada en línea.
Si está ejecutando esto usando el Inicio rápido a continuación, puede dejar la configuración como está y todo debería funcionar. Si está implementando SSS usando web.py en Apache, deberá cambiar el objeto de configuración de CherryPyConfiguration a ApacheConfiguration, lo cual se puede hacer al final del archivo.
SSS proporciona un modelo de objetos, dos implementaciones de API web (para web.py y pylons) y una interfaz de servidor que se implementará para vincular la API SWORD al servidor subyacente.
La interfaz que implementará el servidor es sss.SwordServer. Luego, esto se puede configurar en el archivo de configuración sss.conf.json que SSS utiliza para cargar como implementación del servidor.
La API Web.py está en sss.webpy y solo se puede ejecutar de forma independiente. Este es el uso recomendado de SSS para la implementación de referencia (ver más abajo)
La API de Pylons está en sss.pylons_sword_controller y se puede importar a un proyecto de Pylons muy fácilmente. Debes crear un nuevo controlador en tu proyecto Pylons y hacer que el cuerpo de ese controlador sea simplemente:
from sss.pylons_sword_controller import SwordController __controller__ = "SwordController"
Cuando se ejecuta como implementación de referencia, SSS responde a las solicitudes como si fuera un servidor SWORD 2.0 real, aunque en el fondo es un almacén de archivos simple que realiza un procesamiento mínimo del contenido con el que trabaja.
NOTA: el uso de CherryPy de fábrica no es compatible con HTTP 1.1 (debido a un error), por lo que deberá emitir solicitudes con HTTP 1.0. Esto es una molestia, por lo que para usos distintos al uso de CURL, se recomienda ejecutar SSS detrás de Apache, como se describe más adelante...
Para iniciar SSS usando CherryPy, coloque sss.py en su propio directorio adecuado e inícielo con
python sss.py
Esto iniciará el servidor web en
http://localhost:8080/
Tenga en cuenta que SSS crea automáticamente un almacén de datos en el directorio en el que se encuentra el archivo sss.py, por lo que esto debe hacerse en un directorio adecuado. Para iniciar el servidor en un puerto alternativo (por ejemplo, 8443), inícielo con
python sss.py 8443
Para obtener compatibilidad con HTTP 1.1, es necesario implementar SSS en Apache (CherryPy no es compatible con HTTP 1.1 en este momento debido a un error).
Para ello, puedes seguir las instrucciones en:
http://webpy.org/cookbook/mod_wsgi-apache
Al configurar su archivo httpd.conf, para permitir que las cargas de archivos utilicen Transfer-Encoding: fragmentado y para garantizar que se reenvíen las credenciales de autorización, deberá configurar la configuración de la siguiente manera:
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>
Tenga en cuenta que esto establece una ubicación explícita para wsgi_module (requerido para Ubuntu, YMMV en otras plataformas) y agrega WSGIChunkedRequest al contexto correcto.
Esta sección describe una serie de solicitudes CURL que utilizan cada parte del servicio web SWORD.
Tenga en cuenta que para las solicitudes POST y PUT utilizamos HTTP 1.0 para las solicitudes curl. Esto se debe a que el servidor web CherryPy bajo el cual SSS opera de forma nativa no responde adecuadamente a esas solicitudes (aunque la funcionalidad del servidor no se ve afectada). Es posible que la programación contra SSS requiera el uso explícito de HTTP 1.0; esto NO debe considerarse un requisito para SWORD 2.0.
###Autenticación
Para ver los distintos resultados de autenticación, pruebe las siguientes solicitudes en el documento de servicio. De forma predeterminada, SSS tiene los siguientes detalles de usuario:
usuario: espada
contraseña: espada
En nombre de: obo
curl -i http://espada:espada@localhost:8080/sd-uri
Autenticación exitosa sin un usuario en nombre de
curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri
Autenticación exitosa con un usuario en nombre de
curl -i http://localhost:8080/sd-uri
No se proporcionaron credenciales de autenticación básica, respuesta 401 no autorizada
curl -i http://sword:drows@localhost:8080/sd-uri
Contraseña incorrecta, respuesta 401 no autorizada
curl -i http://drows:sword@localhost:8080/sd-uri
Usuario incorrecto, respuesta 401 no autorizada
curl -i -H "X-On-Behalf-Of: bob" http://sword:sword@localhost:8080/sd-uri
Usuario correcto pero usuario en nombre de no válido, respuesta 401 no autorizada
Todas las solicitudes posteriores se pueden realizar con un encabezado X-On-Behalf-Of; no se proporcionarán más ejemplos
###Obtenga el documento de servicio
HTTP: OBTENER en SD-URI
curl -i http://sword:sword@localhost:8080/sd-uri
Esto devuelve el documento de servicio con el número configurado de colecciones enumeradas.
###Depositar contenido nuevo
HTTP: PUBLICAR en 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]
Esto publica el archivo example.zip en Col-URI con el nombre de archivo "example.zip" y especifica que es un archivo zip. Sin el encabezado X-Packaging, esto se interpretará como un paquete SWORD predeterminado. Col-URI debe obtenerse del Documento de servicio.
Esto debería devolver un estado HTTP de 201 Creado y un recibo de depósito.
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]
Esto debería devolver un estado HTTP de 202 Aceptado y un recibo de depósito.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Col-URI]
Esto imitará un depósito de Atom Multipart y creará dos elementos en el contenedor: atom.xml y example.xml (con el prefijo de la marca de tiempo actual). Esto debería devolver un estado HTTP de 201 Creado y un recibo de depósito. Puedes agregar
-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]
Este es un ejemplo que utiliza un formato de paquete diferente para ejemplo.zip. Por el momento, el empaquetador de ingesta en SSS simplemente dejará este paquete como está, sin intentar descomprimirlo.
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]
Este es un ejemplo en el que proporcionamos la suma de verificación MD5 correcta para el artículo, solo para demostrar que funciona con o sin la suma de verificación. Consulte la sección siguiente sobre errores al proporcionar sumas de verificación incorrectas.
###Listar el contenido de una colección
HTTP: OBTENER en Col-URI
curl -i sword:sword@[Col-URI]
Esto devolverá un Atom Feed donde cada atom:entry hace referencia a una colección en la colección especificada. Esto se implementa sólo por conveniencia, por lo que no es un Feed completo; en su lugar, solo contiene un elemento atom:link que contiene el href al Edit-URI para esa colección
###Obtener una representación del contenedor (recurso multimedia)
HTTP: OBTENER en Cont-URI o EM-URI
curl -i [EM-URI]
Obtenga el paquete de difusión predeterminado del servidor. En este caso, curl completa el encabezado Aceptar con " / ". Esto devolverá un archivo de aplicación/zip de todo el contenido del contenedor. Tenga en cuenta que esta solicitud no requiere autenticación, ya que SSS la modela como la cara pública del contenido a modo de ejemplo.
FIXME: este método de negociación de contenidos está en debate, aunque actualmente la SSS lo apoya
curl -i -H "Accept: application/zip;swordpackage=http://www.swordapp.org/package/default" [EM-URI]
Solicite explícitamente un archivo zip en el formato estándar del paquete Sword (que, dicho sea de paso, es un archivo zip simple)
curl -i -H "Accept: application/zip" [EM-URI]
Solicite explícitamente un archivo zip normal del contenido (que resulta que no es diferente del paquete espada estándar)
curl -i -H "Accept: text/html" [EM-URI]
Solicitar explícitamente la representación HTML del recurso multimedia. Esto devolverá un encabezado HTTP 302 Found con un encabezado de Ubicación que apunta a la representación HTML
curl -i -H "Accept: application/vnd+msword" [EM-URI]
Generar un error 415 de tipo de medio no admitido
###Sobrescribir el recurso multimedia existente con uno nuevo
HTTP: PONER en 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]
Esto reemplazará todo el contenido existente en el contenedor identificado con el EM-URI con el archivo example.zip adjunto. El formato del paquete se interpreta como el paquete espada predeterminado. Devolverá un 201 Creado y un Recibo de Depósito
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]
Esto hará lo mismo que arriba, pero devolverá un 202 Aceptado que indica que la actualización ha sido aceptada en el servidor, pero aún no ha sido procesada (obviamente, a efectos de ejemplo; no hace ninguna diferencia con respecto a lo que realmente sucede en el servidor).
FIXME: así no es como funciona AtomPub, en cambio dice que esto debería devolver un 200; el jurado aún no está deliberando sobre SWORD en esto
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]
Esto haría lo mismo que arriba pero le indica al servidor que no actualice los metadatos del artículo en función de este depósito. SSS no implementa actualizaciones de metadatos para paquetes predeterminados que no sean multiparte, por lo que esto no tendrá ningún efecto real, pero es una solicitud válida.
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]
Un ejemplo igual al anterior pero con el encabezado X-Packaging pasado.
###Eliminar el contenido pero no el contenedor
HTTP: ELIMINAR en EM-URI
curl -i -X DELETE sword:sword@[EM-URI]
Esto elimina todo el contenido de la tienda, pero no el contenedor en sí, y devuelve un 200 OK y un recibo de depósito.
###Obtener una representación del contenedor
HTTP: OBTENER en Edit-URI
curl -i sword:sword@[Edit-URI]
Esto recupera el Edit-URI en su formato predeterminado, que es como una copia del recibo de depósito: un documento de entrada atómica.
curl -i -H "Accept: application/rdf+xml" sword:sword@[Edit-URI]
Esto nos da la declaración RDF/XML pura del repositorio.
curl -i -H "Accept: application/atom+xml;type=entry" sword:sword@[Edit-URI]
Esto solicita explícitamente el Edit-URI en su formulario de entrada atómica, que es el mismo que el formato predeterminado.
###Actualizar un contenedor agregando contenido nuevo al contenido existente
HTTP: PUBLICAR en Editar-URI
curl -i --http1.0 --data-binary "@example.zip" -H "Content-Disposition: filename=example.zip" -H "Content-Type: application/zip" sword:sword@[Edit-URI]
Esto agrega el archivo example.zip al servidor (observe que Content-Disposition le da el mismo nombre; SSS localizará los nombres al recibirlos para evitar sobrescribir los archivos existentes) sin eliminar nada del contenido existente. Esto devolverá un 201 Creado (o si agrega el encabezado X-In-Progress un 202 Aceptado) y el Recibo de depósito.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Edit-URI]
Esto imitará un depósito de Atom Multipart y creará dos elementos en el contenedor: atom.xml y example.xml (con el prefijo de la marca de tiempo actual). En este caso, atom.xml sobrescribirá cualquier archivo atom.xml existente, mientras que example.zip simplemente se agregará con un nombre localizado. Esto debería devolver un estado HTTP de 201 Creado y un recibo de depósito. Puede agregar -H "X-In-Progress: true" para obtener un 202 Aceptado, como se indicó anteriormente.
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]
Esta versión de la solicitud, con el encabezado X-Suppress-Metadata configurado, hará lo mismo que el anterior, pero no intentará extraer ningún metadato del archivo atom.xml como lo habría hecho de otra manera.
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]
###Eliminar el contenedor y todo su contenido.
HTTP: ELIMINAR en Edit-URI
curl -i -X DELETE sword:sword@[Edit-URI]
Esto eliminará todo el contenido del contenedor seguido del propio contenedor. Devolverá una respuesta 204 Sin contenido sin cuerpo de respuesta.
###Generando errores
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]
Genera una respuesta de error ErrorContent al depositar un paquete cuyo tipo de paquete no coincide con el encabezado X-Packaging
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]
Genera un error por una falta de coincidencia entre la suma de verificación y el encabezado de la suma de verificación proporcionado, lo que genera un error 412 Precondition Failed.
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]
Genere un error de Solicitud incorrecta al pasar un valor ilegal a X-In-Progress, lo que resulta en una respuesta de Solicitud incorrecta 400
