openstack-manuals/doc/user-guide/source/cli-swift-archive-auto-extract.rst

Auto-extract archive files

To discover whether your Object Storage system supports this feature, see 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:

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.

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.

{
   "Number Files Created":1,
   "Errors":[
      [
         "/v1/12345678912345/mycontainer/home/xx%3Cyy",
         "400 Bad Request"
      ],
      [
         "/v1/12345678912345/mycontainer/../image.gif",
         "400 Bad Request"
      ]
   ]
}