b94d0b58d4
Adds the following changes: - Renames all the RST files in the user-guide folder to use hyphens instead of underscores; - Adds redirects to the renamed files to .htaccess. Change-Id: Ic5f1a90421add35d001363cd39bada0b56a04d7f Implements: blueprint consistency-file-rename
133 lines
3.7 KiB
ReStructuredText
133 lines
3.7 KiB
ReStructuredText
.. _archive-auto-extract:
|
|
|
|
==========================
|
|
Auto-extract archive files
|
|
==========================
|
|
|
|
To discover whether your Object Storage system supports this feature,
|
|
see :ref:`discoverability`. Alternatively, check with your service
|
|
provider.
|
|
|
|
Use the auto-extract archive feature to upload a tar archive file.
|
|
|
|
The Object Storage system extracts files from the archive file and
|
|
creates an object.
|
|
|
|
Auto-extract archive request
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To upload an archive file, make a ``PUT`` request. Add the
|
|
``extract-archive=format`` query parameter to indicate that you are
|
|
uploading a tar archive file instead of normal content.
|
|
|
|
Valid values for the ``format`` variable are ``tar``, ``tar.gz``, or
|
|
``tar.bz2``.
|
|
|
|
The path you specify in the ``PUT`` request is used for the location of
|
|
the object and the prefix for the resulting object names.
|
|
|
|
In the ``PUT`` request, you can specify the path for:
|
|
|
|
- An account
|
|
|
|
- Optionally, a specific container
|
|
|
|
- Optionally, a specific object prefix
|
|
|
|
For example, if the first object in the tar archive is
|
|
``/home/file1.txt`` and you specify the
|
|
``/v1/12345678912345/mybackup/castor/`` path, the operation creates the
|
|
``castor/home/file1.txt`` object in the ``mybackup`` container in the
|
|
``12345678912345`` account.
|
|
|
|
Create an archive for auto-extract
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You must use the tar utility to create the tar archive file.
|
|
|
|
You can upload regular files but you cannot upload other items (for
|
|
example, empty directories or symbolic links).
|
|
|
|
You must UTF-8-encode the member names.
|
|
|
|
The archive auto-extract feature supports these formats:
|
|
|
|
- The POSIX.1-1988 Ustar format.
|
|
|
|
- The GNU tar format. Includes the long name, long link, and sparse
|
|
extensions.
|
|
|
|
- The POSIX.1-2001 pax format.
|
|
|
|
Use gzip or bzip2 to compress the archive.
|
|
|
|
Use the ``extract-archive`` query parameter to specify the format.
|
|
Valid values for this parameter are ``tar``, ``tar.gz``, or
|
|
``tar.bz2``.
|
|
|
|
Auto-extract archive response
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When Object Storage processes the request, it performs multiple
|
|
sub-operations. Even if all sub-operations fail, the operation returns a
|
|
201 ``Created`` status. Some sub-operations might succeed while others
|
|
fail. Examine the response body to determine the results of each
|
|
auto-extract archive sub-operation.
|
|
|
|
You can set the ``Accept`` request header to one of these values to
|
|
define the response format:
|
|
|
|
``text/plain``
|
|
Formats response as plain text. If you omit the ``Accept`` header,
|
|
``text/plain`` is the default.
|
|
|
|
``application/json``
|
|
Formats response as JSON.
|
|
|
|
``application/xml``
|
|
Formats response as XML.
|
|
|
|
``text/xml``
|
|
Formats response as XML.
|
|
|
|
The following auto-extract archive files example shows a ``text/plain``
|
|
response body where no failures occurred:
|
|
|
|
.. code-block:: console
|
|
|
|
Number Files Created: 10
|
|
Errors:
|
|
|
|
The following auto-extract archive files example shows a ``text/plain``
|
|
response where some failures occurred. In this example, the Object
|
|
Storage system is configured to reject certain character strings so that
|
|
the 400 Bad Request error occurs for any objects that use the restricted
|
|
strings.
|
|
|
|
.. code-block:: console
|
|
|
|
Number Files Created: 8
|
|
Errors:
|
|
/v1/12345678912345/mycontainer/home/xx%3Cyy, 400 Bad Request
|
|
/v1/12345678912345/mycontainer/../image.gif, 400 Bad Request
|
|
|
|
The following example shows the failure response in ``application/json``
|
|
format.
|
|
|
|
.. code-block:: json
|
|
|
|
{
|
|
"Number Files Created":1,
|
|
"Errors":[
|
|
[
|
|
"/v1/12345678912345/mycontainer/home/xx%3Cyy",
|
|
"400 Bad Request"
|
|
],
|
|
[
|
|
"/v1/12345678912345/mycontainer/../image.gif",
|
|
"400 Bad Request"
|
|
]
|
|
]
|
|
}
|
|
|