Download do Simple Sword Server - Download do código-fonte do Simple Sword Server

SSS - Servidor SWORD Simples

Autor: Richard Jones

Introdução

O Simple Sword Server deve usar:

1/ É uma biblioteca de servidor para servidores python usarem para serem compatíveis com SWORDv2 2/ É um servidor independente que fornece uma implementação de referência da especificação SWORD 2.0

Pré-requisitos

O SSS depende de web.py e lxml, então você precisará easy_install de ambos antes de continuar. Você precisará ter libxml2 e libxslt1.1 instalados para que o lxml seja instalado.

Configuração

O SSS possui um objeto de configuração que pode ser modificado para alterar alguns aspectos de seu comportamento. Abra sss.py para edição e encontre o objeto Configuration; cada uma das opções disponíveis para você é documentada in-line.

Se você estiver executando isso usando o Início rápido abaixo, poderá deixar a configuração como está e tudo deverá funcionar. Se você estiver implantando SSS usando web.py no Apache, precisará alterar o objeto de configuração de CherryPyConfiguration para ApacheConfiguration, o que pode ser feito no final do arquivo.

Como uma biblioteca de servidor

SSS fornece um modelo de objeto, duas implementações de API web (para web.py e pylons) e uma interface de servidor a ser implementada para vincular a API SWORD ao servidor subjacente.

Implementando a API do servidor

A interface a ser implementada pelo servidor é sss.SwordServer. Isso pode então ser configurado no arquivo de configuração sss.conf.json que é usado pelo SSS para carregar como a implementação do servidor.

Utilizando a API da web web.py

A API Web.py está em sss.webpy e só pode ser executada de forma independente. Este é o uso recomendado de SSS para implementação de referência (veja abaixo)

Utilizando a API da web pylons

A API Pylons está em sss.pylons_sword_controller e pode ser importada para um projeto Pylons com muita facilidade. Você deve criar um novo controlador em seu projeto Pylons e fazer com que o corpo desse controlador seja simplesmente:

 from sss.pylons_sword_controller import SwordController
__controller__ = "SwordController"

Como uma implementação de referência

Quando executado como uma implementação de referência, o SSS responde às solicitações como se fosse um servidor SWORD 2.0 real, embora nos bastidores seja um armazenamento de arquivos simples que realiza processamento mínimo no conteúdo com o qual trabalha.

Início rápido

NOTA: usar o CherryPy pronto para uso não suporta HTTP 1.1 (devido a um bug), então você precisará emitir solicitações com HTTP 1.0. Isso é um incômodo, portanto, para usos diferentes do CURL, é recomendado executar o SSS por trás do Apache, conforme descrito mais abaixo...

Para iniciar o SSS usando CherryPy, coloque sss.py em seu próprio diretório adequado e inicie-o com

 python sss.py

Isso iniciará o servidor web em

 http://localhost:8080/

Observe que o SSS cria automaticamente um armazenamento de dados no diretório em que o arquivo sss.py está localizado, portanto, isso deve ser feito em um diretório adequado. Para iniciar o servidor em uma porta alternativa (por exemplo, 8443) inicie-o com

 python sss.py 8443

Implantação no Apache

Para obter suporte HTTP 1.1, é necessário implantar SSS no Apache (o CherryPy não suporta HTTP 1.1 neste momento devido a um bug)

Para fazer isso, você pode seguir as instruções em:

 http://webpy.org/cookbook/mod_wsgi-apache

Ao configurar seu arquivo httpd.conf, para permitir que uploads de arquivos usem Transfer-Encoding: chunked e para garantir que as credenciais de autorização sejam encaminhadas, você precisará definir a configuração da seguinte forma:

 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


    WSGIChunkedRequest On 
    Order deny,allow
    Allow from all

Observe que isso define um local explícito para wsgi_module (obrigatório para Ubuntu, YMMV em outras plataformas) e adiciona WSGIChunkedRequest ao contexto correto.

Solicitações ao servidor com CURL

Esta seção descreve uma série de solicitações CURL que utilizam cada parte do serviço web SWORD

Observe que para solicitações POST e PUT usamos HTTP 1.0 para solicitações curl. Isso ocorre porque o servidor web CherryPy sob o qual o SSS opera nativamente não responde adequadamente a essas solicitações (embora a funcionalidade do servidor não seja afetada). Você pode descobrir que a programação no SSS exigirá o uso explícito do HTTP 1.0 - isso NÃO deve ser considerado um requisito para o SWORD 2.0.

###Autenticação

Para ver os vários resultados de autenticação, tente as seguintes solicitações no documento de serviço. Por padrão, o SSS possui os seguintes detalhes do usuário:

usuário: espada
senha: espada
Em nome de: obo
curl -i http://espada:espada@localhost:8080/sd-uri

Autenticação bem-sucedida sem um usuário em nome de

 curl -i -H "X-On-Behalf-Of: obo" http://sword:sword@localhost:8080/sd-uri

Autenticação bem-sucedida com um usuário em nome de

 curl -i http://localhost:8080/sd-uri

Nenhuma credencial de autenticação básica fornecida, 401 Resposta não autorizada

 curl -i http://sword:drows@localhost:8080/sd-uri

Senha incorreta, resposta 401 não autorizada

 curl -i http://drows:sword@localhost:8080/sd-uri

Usuário incorreto, resposta 401 não autorizada

 curl -i -H "X-On-Behalf-Of: bob" http://sword:sword@localhost:8080/sd-uri

Usuário correto, mas usuário em nome de usuário inválido, resposta 401 não autorizada

Todas as solicitações subsequentes podem ser feitas com um cabeçalho X-On-Behalf-Of; nenhum outro exemplo será fornecido

###Obtenha o Documento de Serviço

HTTP: GET em SD-URI

 curl -i http://sword:sword@localhost:8080/sd-uri

Isso retorna o Documento de Serviço com o número configurado de coleções listadas

###Deposite algum conteúdo novo

HTTP: POST em 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]

Isso envia o arquivo example.zip para o Col-URI com o nome de arquivo "example.zip" e especificando que é um arquivo zip. Sem o cabeçalho X-Packaging, isso será interpretado como um pacote SWORD padrão. Col-URI deve ser obtido no Documento de Serviço.

Isso deve retornar um status HTTP de 201 Criado e um 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]

Isso deve retornar um status HTTP de 202 Aceito e um 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]

Isso imitará um depósito Atom Multipart e criará dois itens no contêiner: atom.xml e example.xml (prefixados com o carimbo de data/hora atual). Isso deve retornar um status HTTP de 201 Criado e um Recibo de Depósito. Você pode adicionar

 -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 é um exemplo que usa um formato de pacote diferente para example.zip. No momento, o empacotador de ingestão no SSS simplesmente deixará este pacote como está, sem tentar descompactá-lo

 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 é um exemplo onde fornecemos a soma de verificação MD5 correta para o item, apenas para demonstrar que funciona com ou sem a soma de verificação. Consulte a seção abaixo sobre erros para fornecer somas de verificação incorretas.

###Liste o conteúdo de uma coleção

HTTP: GET em Col-URI

 curl -i sword:sword@[Col-URI]

Isso retornará um Atom Feed onde cada atom:entry se refere a uma coleção na coleção especificada. Isso é implementado apenas por conveniência, portanto não é um Feed completo; em vez disso, ele contém apenas um elemento atom:link contendo o href para o Edit-URI dessa coleção

###Obtenha uma representação do contêiner (recurso de mídia)

HTTP: GET no Cont-URI ou EM-URI

 curl -i [EM-URI]

Obtenha o pacote de disseminação padrão do servidor. Neste caso, curl preenche o cabeçalho Accept para nós com " / ". Isso retornará um arquivo aplicativo/zip de todo o conteúdo do contêiner. Observe que esta solicitação não requer autenticação, pois o SSS modela isso como a face pública do conteúdo para fins de exemplo.

FIXME: este método de negociação de conteúdo está em debate, embora o SSS atualmente o apoie

 curl -i -H "Accept: application/zip;swordpackage=http://www.swordapp.org/package/default" [EM-URI]

Solicite explicitamente um arquivo zip no formato padrão do pacote espada (que é, aliás, um arquivo zip simples)

 curl -i -H "Accept: application/zip" [EM-URI]

Solicite explicitamente um arquivo zip comum do conteúdo (que não é diferente do pacote padrão do Sword)

 curl -i -H "Accept: text/html" [EM-URI]

Solicite explicitamente a representação HTML do recurso de mídia. Isso retornará um cabeçalho HTTP 302 Found com um cabeçalho Location que aponta para a representação HTML

 curl -i -H "Accept: application/vnd+msword" [EM-URI]

Gerar um erro 415 Tipo de mídia não suportado

###Substituir o recurso de mídia existente por um novo

HTTP: PUT em 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]

Isso substituirá todo o conteúdo existente no contêiner identificado com o EM-URI pelo arquivo example.zip anexado. O formato do pacote é interpretado como o pacote espada padrão. Ele retornará um 201 Criado e um 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]

Isso fará o mesmo que acima, mas retornará um 202 Aceito indicando que a atualização foi aceita no servidor, mas ainda não foi processada (para fins de exemplo, obviamente; não faz nenhuma diferença para o que realmente acontece no servidor).

FIXME: não é assim que o AtomPub funciona, em vez disso diz que deveria retornar 200 - o júri ainda não decidiu pelo SWORD sobre isso

 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]

Isso faria o mesmo que acima, mas informa ao servidor para não atualizar os metadados do item com base neste depósito. O SSS não implementa atualizações de metadados para pacotes padrão que não são multipartes, portanto isso não terá nenhum efeito real, mas é uma solicitação 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]

Um exemplo igual ao acima, mas com o cabeçalho X-Packaging passado.

###Exclua o conteúdo, mas não o contêiner

HTTP: DELETE em EM-URI

 curl -i -X DELETE sword:sword@[EM-URI]

Isso exclui todo o conteúdo da loja, mas não o contêiner em si, e retorna um 200 OK e um recibo de depósito

###Obtenha uma representação do contêiner

HTTP: GET no Edit-URI

 curl -i sword:sword@[Edit-URI]

Isso recupera o Edit-URI em seu formato padrão, que é uma cópia do Recibo de Depósito - um documento de entrada atom

 curl -i -H "Accept: application/rdf+xml" sword:sword@[Edit-URI]

Isso nos dá a instrução RDF/XML pura do repositório

 curl -i -H "Accept: application/atom+xml;type=entry" sword:sword@[Edit-URI]

Isso solicita explicitamente o Edit-URI em seu formulário de entrada atom, que é igual ao formato padrão

###Atualize um contêiner adicionando novo conteúdo ao conteúdo existente

HTTP: POST em 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]

Isso adiciona o arquivo example.zip ao servidor (observe que Content-Disposition fornece o mesmo nome - o SSS localizará os nomes no recebimento para evitar a substituição de arquivos existentes) sem remover nenhum conteúdo existente. Isso retornará um 201 Criado (ou se você adicionar o cabeçalho X-In-Progress um 202 Aceito) e o 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]

Isso imitará um depósito Atom Multipart e criará dois itens no contêiner: atom.xml e example.xml (prefixados com o carimbo de data/hora atual). O atom.xml substituirá qualquer arquivo atom.xml existente neste caso, enquanto o example.zip será apenas adicionado com um nome localizado. Isso deve retornar um status HTTP de 201 Criado e um Recibo de Depósito. Você pode adicionar -H "X-In-Progress: true" para obter um 202 Accepted de volta, como acima.

 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 versão da solicitação, com o cabeçalho X-Suppress-Metadata definido, fará o mesmo que acima, mas não tentará extrair nenhum metadado do arquivo atom.xml como faria de outra forma.

 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]

###Exclua o contêiner e todo o seu conteúdo

HTTP: DELETE no Edit-URI

 curl -i -X DELETE sword:sword@[Edit-URI]

Isso removerá todo o conteúdo do contêiner, seguido pelo próprio contêiner. Ele retornará uma resposta 204 No Content sem corpo de resposta.

###Gerando erros

 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]

Gera uma resposta de erro ErrorContent ao depositar um pacote cujo tipo de pacote não corresponde ao cabeçalho 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]

Gere um erro devido a uma incompatibilidade entre a soma de verificação e o cabeçalho da soma de verificação fornecido, resultando em um erro 412 Falha na condição prévia.

 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]

Gere um erro de Bad Request passando um valor ilegal para X-In-Progress, resultando em uma resposta 400 Bad Request

Expandir