Auto-extract archive files

To discover whether your Object Storage system supports this feature, see the section called “Discoverability”. Alternatively, check with your service provider.

Use the auto-extract archive feature to upload a tar(1) 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, you make a PUT request. Add the extract-archive=format query parameter to indicate that you are uploading a tar(1) 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 a prefix for the resulting object names.

For example, if the first object in the tar(1) 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.

In the PUT request, you can specify the path for:

  • An account

  • Optionally, a specific container

  • Optionally, a specific object prefix

 Create an archive for auto-extract

You must use the tar(1) utility to create the tar(1) archive file.

You can upload regular files but you cannot upload other items, such as empty directories, symbolic links, and so on.

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(1) or bzip2(1) 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 or 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"
      ]
   ]
}
Questions? Discuss on ask.openstack.org
Found an error? Report a bug against this page

loading table of contents...