From eb7ec826da38b0f97e35bc5a736f4b331b2c4216 Mon Sep 17 00:00:00 2001 From: Sean Hammond Date: Mon, 9 Dec 2013 13:50:18 +0100 Subject: [PATCH] General edit of new FileStore docs Edit text for clarity, simplicity. --- doc/filestore.rst | 55 ++++++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/doc/filestore.rst b/doc/filestore.rst index 60f7a066da2..0c9e3eb4f1c 100644 --- a/doc/filestore.rst +++ b/doc/filestore.rst @@ -2,8 +2,13 @@ FileStore and file uploads ========================== -CKAN allows users to upload files directly to it against a resource or images -displayed against groups and organizations. +When enabled, CKAN's FileStore allows users to upload data files to CKAN +resources, and to upload logo images for groups and organizations. Users will +see an upload button when creating or updating a resource, group or +organization. + +.. versionadded:: 2.2 + Uploading logo images for groups and organizations was added in CKAN 2.2. .. versionchanged:: 2.2 Previous versions of CKAN used to allow uploads to remote cloud hosting but @@ -23,16 +28,17 @@ To setup CKAN's FileStore with local file storage: sudo mkdir -p |storage_path| -2. Add the following lines to your CKAN config file, after the ``[app:main]`` +2. Add the following line to your CKAN config file, after the ``[app:main]`` line: .. parsed-literal:: ckan.storage_path = |storage_path| -3. Set the permissions of the :ref:`ckan.storage_path`. For example if you're running - CKAN with Apache, then Apache's user (``www-data`` on Ubuntu) must have - read, write and execute permissions for the :ref:`ckan.storage_path`: +3. Set the permissions of your :ref:`ckan.storage_path` directory. + For example if you're running CKAN with Apache, then Apache's user + (``www-data`` on Ubuntu) must have read, write and execute permissions for + the :ref:`ckan.storage_path`: .. parsed-literal:: @@ -46,36 +52,33 @@ To setup CKAN's FileStore with local file storage: |reload_apache| ------------------------ -FileStore web interface ------------------------ - -Upload of files to storage is integrated directly into the Dataset creation -and editing system with files being associated to Resources. - ------------- FileStore API ------------- .. versionchanged:: 2.2 - The previous API has been deprecated although should still work if you where - using local file storage. + The FileStore API was redesigned for CKAN 2.2. + The previous API has been deprecated. -The API is part of the :py:func:`~ckan.logic.action.create.resource_create` and +Files can be uploaded to the FileStore using the +:py:func:`~ckan.logic.action.create.resource_create` and :py:func:`~ckan.logic.action.update.resource_update` action API functions. You can post mutipart/form-data to the API and the key, value pairs will treated as as if they are a JSON object. The extra key ``upload`` is used to actually post the binary data. -Curl automatically puts the multipart-form-data heading when using the -``--form`` option: +For example, to create a new CKAN resource and upload a file to it using +`curl `_: .. parsed-literal:: curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_create' --form upload=@filetoupload --form package_id=my_dataset -The Python requests library used the files parameter and automatically sets -the multipart/form-data header too: +(Curl automatically sends a ``multipart-form-data`` heading with you use the +``--form`` option.) + +To create a new resource and upload a file to it using the Python library +`requests `_: .. parsed-literal:: @@ -85,13 +88,17 @@ the multipart/form-data header too: headers={"X-CKAN-API-Key": "21a47217-6d7b-49c5-88f9-72ebd5a4d4bb"}, files=[('upload', file('/path/to/file/to/upload.csv'))]) -With :py:func:`~ckan.logic.action.update.resource_update`, if you want to -override a file you just need to set the upload field again:: +(Requests automatically sends a ``multipart-form-data`` heading when you use the +``files=`` parameter.) + +To overwrite an uploaded file with a new version of the file, post to the +:py:func:`~ckan.logic.action.update.resource_update` action and use the +``upload`` field:: curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_update' --form upload=@newfiletoupload --form id=resourceid -If you want to clear the upload and change it for a remote URL -there is special boolean field clear_upload to do this:: +To replace an uploaded file with a link to a file at a remote URL, use the +``clear_upload`` field:: curl -H'Authorization: your-api-key' 'http://yourhost/api/action/resource_update' --form url=http://expample.com --form clear_upload=true --form id=resourceid