Simple Sword Server
1.0.0
Автор: Ричард Джонс
Сервер Simple Sword должен использовать:
1/ Это серверная библиотека для серверов Python, которую можно использовать для совместимости с SWORDv2. 2/ Это автономный сервер, который обеспечивает эталонную реализацию спецификации SWORD 2.0.
SSS зависит от web.py и lxml, поэтому вам нужно будет установить оба из них, прежде чем продолжить. Для установки lxml вам потребуется установить libxml2 и libxslt1.1.
У SSS есть объект конфигурации, который можно изменить, чтобы изменить некоторые аспекты его поведения. Откройте sss.py для редактирования и найдите объект Configuration; каждый из доступных вам вариантов документирован в режиме реального времени.
Если вы запускаете это с помощью приведенного ниже быстрого запуска, вы можете оставить конфигурацию как есть, и все должно работать. Если вы развертываете SSS с помощью web.py под Apache, вам нужно будет изменить объект конфигурации с CherryPyConfiguration на ApacheConfiguration, что можно сделать в конце файла.
SSS предоставляет объектную модель, две реализации веб-API (для web.py и pylons) и серверный интерфейс, который необходимо реализовать для привязки SWORD API к базовому серверу.
Интерфейс, который будет реализован сервером, — sss.SwordServer. Затем это можно настроить в файле конфигурации sss.conf.json, который используется SSS для загрузки в качестве реализации сервера.
API Web.py находится в sss.webpy и может запускаться только автономно. Это рекомендуемое использование SSS для эталонной реализации (см. ниже).
API Pylons находится в sss.pylons_sword_controller и его можно очень легко импортировать в проект Pylons. Вам следует создать новый контроллер в своем проекте Pylons, и тело этого контроллера будет просто:
from sss.pylons_sword_controller import SwordController __controller__ = "SwordController"
При запуске в качестве эталонной реализации SSS отвечает на запросы так, как если бы это был настоящий сервер SWORD 2.0, хотя внутри это простое хранилище файлов, которое выполняет минимальную обработку контента, с которым работает.
ПРИМЕЧАНИЕ. Использование CherryPy «из коробки» не поддерживает HTTP 1.1 (из-за ошибки), поэтому вам придется отправлять запросы с помощью HTTP 1.0. Это неприятно, поэтому для других целей, кроме использования CURL, рекомендуется запускать SSS за Apache, как описано ниже...
Чтобы запустить SSS с использованием CherryPy, поместите sss.py в отдельный подходящий каталог и запустите его с помощью
python sss.py
Это запустит веб-сервер по адресу
http://localhost:8080/
Обратите внимание, что SSS автоматически создает хранилище данных в каталоге, в котором находится файл sss.py, поэтому это следует делать в подходящем каталоге. Чтобы запустить сервер на альтернативном порту (например, 8443), запустите его с помощью
python sss.py 8443
Чтобы получить поддержку HTTP 1.1, необходимо развернуть SSS под Apache (CherryPy на данный момент не поддерживает HTTP 1.1 из-за ошибки)
Для этого вы можете следовать инструкциям по адресу:
http://webpy.org/cookbook/mod_wsgi-apache
При настройке файла httpd.conf, чтобы разрешить загрузку файлов с использованием Transfer-Encoding: chunked и обеспечить пересылку учетных данных авторизации, вам необходимо настроить конфигурацию следующим образом:
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>
Обратите внимание, что это устанавливает явное местоположение для wsgi_module (требуется для Ubuntu, YMMV на других платформах) и добавляет WSGIChunkedRequest в правильный контекст.
В этом разделе описывается серия запросов CURL, которые используют каждую часть веб-сервиса SWORD.
Обратите внимание, что для запросов POST и PUT мы используем HTTP 1.0 для запросов на завихрение. Это связано с тем, что веб-сервер CherryPy, под которым работает SSS, изначально не отвечает на эти запросы должным образом (хотя на функциональность сервера это не влияет). Вы можете обнаружить, что программирование с использованием SSS потребует от вас явного использования HTTP 1.0 — это НЕ следует считать требованием для SWORD 2.0.
###Аутентификация
Чтобы увидеть различные результаты аутентификации, попробуйте выполнить следующие запросы к служебному документу. По умолчанию SSS имеет следующие данные пользователя:
пользователь: меч
пароль: меч
От имени: обо
локон -я http://sword:sword@localhost:8080/sd-uri
Успешная аутентификация без участия пользователя от имени пользователя
curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri
Успешная аутентификация с пользователем от имени пользователя
curl -i http://localhost:8080/sd-uri
Учетные данные базовой аутентификации не предоставлены, 401 Несанкционированный ответ
curl -i http://sword:drows@localhost:8080/sd-uri
Неверный пароль, 401 несанкционированный ответ.
curl -i http://drows:sword@localhost:8080/sd-uri
Неверный пользователь, 401 несанкционированный ответ.
curl -i -H "X-On-Behalf-Of: bob" http://sword:sword@localhost:8080/sd-uri
Правильный пользователь, но недействительный пользователь от имени, 401 несанкционированный ответ
Все последующие запросы могут выполняться с заголовком X-On-Behalf-Of; никаких дополнительных примеров приводиться не будет
###Получите сервисный документ
HTTP: GET по SD-URI
curl -i http://sword:sword@localhost:8080/sd-uri
Это возвращает служебный документ с указанным настроенным количеством коллекций.
###Внесите новый контент
HTTP: POST по 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]
При этом файл example.zip будет отправлен в Col-URI с именем файла «example.zip» и указанием, что это zip-файл. Без заголовка X-Packaging это будет интерпретироваться как пакет SWORD по умолчанию. Col-URI следует получить из служебного документа.
Это должно вернуть статус HTTP 201 Created и депозитную квитанцию.
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]
Это должно вернуть HTTP-статус 202 Accepted и депозитную квитанцию.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Col-URI]
Это будет имитировать депозит Atom Multipart и создаст в контейнере два элемента: атом.xml и example.xml (с префиксом текущей метки времени). Это должно вернуть статус HTTP 201 Created и депозитную квитанцию. Вы можете добавить
-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]
Это пример использования другого формата пакета для example.zip. На данный момент упаковщик в SSS просто оставит этот пакет как есть, не пытаясь его распаковать.
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]
Это пример, в котором мы указываем правильную контрольную сумму MD5 для элемента, просто чтобы продемонстрировать, что это работает с контрольной суммой или без нее. См. раздел ниже об ошибках, связанных с предоставлением неверных контрольных сумм.
###Перечислить содержимое коллекции
HTTP: GET по Col-URI
curl -i sword:sword@[Col-URI]
Это вернет канал атомов, где каждый атом: запись ссылается на коллекцию в указанной коллекции. Это реализовано только ради удобства, поэтому не является полноценным фидом; вместо этого он просто содержит элементatom:link, содержащий ссылку на Edit-URI для этой коллекции.
###Получить представление контейнера (медиа-ресурс)
HTTP: GET по Cont-URI или EM-URI.
curl -i [EM-URI]
Получите пакет распространения по умолчанию с сервера. В этом случае Curl заполняет для нас заголовок Accept знаком " / ". Это вернет файл приложения/zip со всем содержимым контейнера. Обратите внимание, что этот запрос не требует аутентификации, поскольку SSS моделирует ее как публичную версию контента для примера.
FIXME: этот метод согласования контента обсуждается, хотя SSS в настоящее время его поддерживает.
curl -i -H "Accept: application/zip;swordpackage=http://www.swordapp.org/package/default" [EM-URI]
Явно запросить zip-файл в стандартном формате пакета меча (который, кстати, является простым zip-файлом)
curl -i -H "Accept: application/zip" [EM-URI]
Явно запросить обычный zip-файл с содержимым (который ничем не отличается от стандартного пакета меча)
curl -i -H "Accept: text/html" [EM-URI]
Явно запросите HTML-представление медиа-ресурса. Это вернет HTTP-заголовок 302 Found с заголовком Location, который указывает на HTML-представление.
curl -i -H "Accept: application/vnd+msword" [EM-URI]
Создать ошибку 415 «Неподдерживаемый тип носителя»
###Заменить существующий медиа-ресурс новым
HTTP: PUT на 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]
Это заменит весь существующий контент в контейнере, указанном с помощью EM-URI, на прикрепленный файл example.zip. Формат пакета интерпретируется как пакет меча по умолчанию. Он вернет 201 Created и депозитную квитанцию.
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]
Это будет делать то же самое, что и выше, но вернет 202 Accepted, указывающее, что обновление было принято на сервер, но еще не обработано (очевидно, для целей примера; это не имеет никакого значения для того, что на самом деле происходит на сервере).
FIXME: AtomPub работает не так, вместо этого он говорит, что должно вернуть 200 - жюри по этому вопросу все еще не принято.
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]
Это будет делать то же самое, что и выше, но сообщит серверу не обновлять метаданные элемента на основе этого депозита. SSS не реализует обновления метаданных для пакетов по умолчанию, которые не являются составными, поэтому это не будет иметь никакого реального эффекта, но это действительный запрос.
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]
Пример того же, что и выше, но с переданным заголовком X-Packaging.
###Удалить содержимое, но не контейнер
HTTP: УДАЛЕНИЕ по EM-URI
curl -i -X DELETE sword:sword@[EM-URI]
Это удаляет весь контент из магазина, но не сам контейнер, и возвращает 200 ОК и депозитную квитанцию.
###Получите представление контейнера
HTTP: GET по Edit-URI
curl -i sword:sword@[Edit-URI]
Это возвращает Edit-URI в формате по умолчанию, который представляет собой копию депозитной квитанции — документа атомной записи.
curl -i -H "Accept: application/rdf+xml" sword:sword@[Edit-URI]
Это дает нам чистый оператор RDF/XML из репозитория.
curl -i -H "Accept: application/atom+xml;type=entry" sword:sword@[Edit-URI]
Это явно запрашивает Edit-URI в форме записи атома, которая совпадает с форматом по умолчанию.
###Обновите контейнер, добавив новое содержимое к существующему.
HTTP: POST на 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]
Это добавит файл example.zip на сервер (обратите внимание, что Content-Disposition присваивает ему то же имя — SSS локализует имена при получении, чтобы избежать перезаписи существующих файлов) без удаления какого-либо существующего содержимого. Это вернет 201 Created (или, если вы добавите заголовок X-In-Progress, 202 Accepted) и депозитную квитанцию.
curl -i --http1.0 --data-binary "@multipart.dat" -H 'Content-Type: multipart/related; boundary="===============0670350989=="' -H "MIME-Version: 1.0" sword:sword@[Edit-URI]
Это будет имитировать депозит Atom Multipart и создаст в контейнере два элемента: атом.xml и example.xml (с префиксом текущей метки времени). В этом случае атом.xml перезапишет любой существующий файл атом.xml, а файл example.zip будет просто добавлен под локализованным именем. Это должно вернуть статус HTTP 201 Created и депозитную квитанцию. Вы можете добавить -H «X-In-Progress: true», чтобы вместо этого получить ответ 202 Accepted, как указано выше.
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]
Эта версия запроса с установленным заголовком X-Suppress-Metadata будет делать то же самое, что и выше, но не будет пытаться извлечь какие-либо метаданные из файлаatom.xml, как это было бы в противном случае.
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]
###Удалить контейнер и все его содержимое
HTTP: УДАЛИТЬ в Edit-URI
curl -i -X DELETE sword:sword@[Edit-URI]
Это приведет к удалению всего содержимого из контейнера, а затем и самого контейнера. Он вернет ответ 204 No Content без тела ответа.
###Генерация ошибок
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]
Генерирует ответ об ошибке ErrorContent при размещении пакета, тип которого не соответствует заголовку 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]
Сгенерируйте ошибку из-за несоответствия между контрольной суммой и предоставленным заголовком контрольной суммы, что приведет к ошибке 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]
Создайте ошибку «Неверный запрос», передав недопустимое значение в X-In-Progress, что приведет к ответу 400 «Неверный запрос».
