Simple Sword Server
1.0.0
著者: リチャード・ジョーンズ
Simple Sword サーバーは以下を使用する必要があります。
1/ SWORDv2 互換にするために使用する Python サーバー用のサーバー ライブラリです。 2/ SWORD 2.0 仕様のリファレンス実装を提供するスタンドアロン サーバーです。
SSS は web.py と lxml に依存しているため、続行する前にこれらの両方を easy_install する必要があります。 lxml をインストールするには、libxml2 と libxslt1.1 をインストールしておく必要があります。
SSS には、動作の一部を変更するために変更できる構成オブジェクトがあります。 編集のために sss.py を開いて、Configuration オブジェクトを見つけます。利用可能な各オプションはインラインで文書化されています。
以下のクイック スタートを使用してこれを実行している場合は、設定をそのままにしておくことができ、すべてが機能するはずです。 Apache で web.py を使用して SSS をデプロイする場合は、構成オブジェクトを CherryPyConfiguration から ApacheConfiguration に変更する必要があります。これはファイルの最後で実行できます。
SSS は、オブジェクト モデル、2 つの Web API 実装 (web.py および pylon 用)、および SWORD API を基盤となるサーバーにバインドするために実装されるサーバー インターフェイスを提供します。
サーバーによって実装されるインターフェースは sss.SwordServer です。 これは、サーバーの実装としてロードするために SSS によって使用される sss.conf.json 構成ファイルで構成できます。
Web.py API は sss.webpy にあり、スタンドアロンでのみ実行できます。 これは、リファレンス実装として推奨される SSS の使用法です (下記を参照)
Pylons API は 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 を使用する以外の用途では、後述するように Apache の背後で SSS を実行することをお勧めします。
CherryPyを使用してSSSを起動するには、sss.pyを独自の適切なディレクトリに配置し、次のように起動します。
python sss.py
これにより、次の場所で Web サーバーが起動します。
http://localhost:8080/
SSS は sss.py ファイルが配置されているディレクトリにデータ ストアを自動的に作成するため、これは適切なディレクトリで行う必要があることに注意してください。 代替ポート (例: 8443) でサーバーを起動するには、次のように起動します。
python sss.py 8443
HTTP 1.1 のサポートを取得するには、Apache に SSS をデプロイする必要があります (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 が正しいコンテキストに追加されることに注意してください。
このセクションでは、SWORD Web サービスの各部分を利用する一連の CURL リクエストについて説明します。
POST リクエストと PUT リクエストでは、curl リクエストに HTTP 1.0 を使用することに注意してください。 これは、SSS がネイティブに動作する CherryPy Web サーバーが、これらのリクエストに適切に応答しないためです (ただし、サーバーの機能は影響を受けません)。 SSS に対するプログラミングでは、明示的に HTTP 1.0 を使用する必要があることがわかりますが、これは SWORD 2.0 の要件とみなされるべきではありません。
###認証
さまざまな認証結果を確認するには、サービス ドキュメントで次のリクエストを試してください。 デフォルトでは、SSS には次のユーザー詳細が含まれます。
使用者：剣
パスワード：剣
代理人：オボ
カール -i http://sword:sword@localhost:8080/sd-uri
On-Behalf-Of ユーザーなしでの認証の成功
curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri
On-Behalf-Of ユーザーによる認証の成功
curl -i http://localhost:8080/sd-uri
Basic 認証資格情報が指定されていない、401 Unauthorized 応答
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
ユーザーは正しいが無効な On-Behalf-Of ユーザー、401 不正応答
後続のすべてのリクエストは、X-On-Behalf-Of ヘッダーを使用して実行できます。これ以上の例は提供されません
###サービス文書を入手する
HTTP: SD-URI で取得
curl -i http://sword:sword@localhost:8080/sd-uri
これにより、構成された数のコレクションがリストされたサービス ドキュメントが返されます。
###新しいコンテンツをデポジットする
HTTP: Col-URI に POST
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 ファイルがファイル名「example.zip」で Col-URI にポストされ、それが 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 デポジットを模倣し、コンテナ内に atom.xml と example.xml (現在のタイムスタンプがプレフィックスとして付く) という 2 つのアイテムを作成します。 これにより、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: Col-URI で GET
curl -i sword:sword@[Col-URI]
これにより、各 atom:entry が指定されたコレクション内のコレクションを参照する Atom フィードが返されます。 これは便宜上のみ実装されているため、完全なフィードではありません。代わりに、そのコレクションの Edit-URI への href を含む atom:link 要素が含まれるだけです。
###コンテナの表現を取得します (メディア リソース)
HTTP: Cont-URI または EM-URI で GET
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]
標準の Sword パッケージ形式の zip ファイル (ちなみに、プレーン zip ファイル) を明示的にリクエストします。
curl -i -H "Accept: application/zip" [EM-URI]
コンテンツの通常の zip ファイルを明示的にリクエストします (これは標準の Sword パッケージと何ら変わりません)
curl -i -H "Accept: text/html" [EM-URI]
メディア リソースの HTML 表現を明示的にリクエストします。 これにより、HTML 表現を指す Location ヘッダーを含む 302 Found HTTP ヘッダーが返されます。
curl -i -H "Accept: application/vnd+msword" [EM-URI]
415 Unsupported Media Type エラーを生成する
###既存のメディア リソースを新しいメディア リソースで上書きします
HTTP: EM-URI に PUT
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 を返します (明らかに例の目的であり、実際の内容とは何の違いもありません)サーバー上で発生します)。
修正: これは AtomPub の仕組みではなく、代わりに 200 を返す必要があると書かれています。この点については SWORD に対する陪審員はまだ出ていません。
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 OK とデポジット領収書が返されます。
###コンテナの表現を取得する
HTTP: Edit-URI で GET
curl -i sword:sword@[Edit-URI]
これにより、Edit-URI がデフォルト形式で取得されます。これは、Deposit Receipt (アトム エントリ ドキュメント) のコピーとして取得されます。
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: Edit-URI への POST
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) と Deposit Receipt が返されます。
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 デポジットを模倣し、コンテナ内に atom.xml と example.xml (現在のタイムスタンプがプレフィックスとして付く) という 2 つのアイテムを作成します。 この場合、atom.xml は既存の atom.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: 編集 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]
パッケージタイプが X-Packaging ヘッダーと一致しないパッケージをデポジットすると、ErrorContent エラー応答を生成します。
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 に不正な値を渡すことで Bad Request エラーを生成し、その結果 400 Bad Request 応答が返されます。
