Create and manage object storage

You can use the simple examples in the following sections for basic Cloud Files requests that you will commonly use. Example requests are provided in cURL, followed by the response.

Note

Generally, each time curl is invoked to perform an operation, a separate TCP/IP and SSL connection is created and then discarded. The language APIs, in contrast, are designed to reuse connections between operations and therefore provide much better performance. We recommend that you use one of the language APIs in your production applications and limit cURL to testing and troubleshooting.

Before running the examples, review the Cloud Files concepts.

Note

These examples use the $API_ENDPOINT, $AUTH_TOKEN, and $TENANT_ID environment variables to specify the API endpoint, authentication token, and account ID values for accessing the service. Make sure you configure these variables before running the code samples.

For more information about all Cloud Files operations, see the Storage API reference and the CDN API reference.

Creating a storage container

Before uploading any data to Cloud Files, you must create a storage container.

To create a container, you send an HTTP PUT request with a valid authentication token.

An HTTP status code of 201 (Created) in the response indicates that the container was successfully created.

Example: cURL create a storage container request

curl -i -X PUT $API_ENDPOINT/v1/$TENANT_ID/yourContainerName \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Create a storage container response

HTTP/1.1 201 Created
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx858f693aeb5d420ea43da-00568d3c5cdfw1
Date: Wed, 06 Jan 2016 16:10:04 GMT

Uploading an object

After creating a container, you can upload a file to it.

To upload an object, you send an HTTP PUT request with a valid authentication token.

You must ensure that the object’s Content-Type is set correctly so that the receiving server knows what kind of file it is. For more information about Content-Type, see the Header Field Definitions in the Hypertext Transfer Protocol. This is the mechanism by which a user’s web browser knows how to display the file or whether to launch a helper application to display the file.

If you know the value of Content-Length, you should also set it in the request. However, when you send the file in the cURL request by using the cURL -T option, cURL, by default, sets the Content-Length correctly by reading the file. In this case, you can omit Content-Length in the request.

An HTTP status code of 201 (Created) in the response indicates that the object was successfully uploaded.

Example: cURL upload an object request

curl -i -X PUT $API_ENDPOINT/v1/$TENANT_ID/yourContainerName/yourObjectName \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "Content-Type: image/jpeg” \
-H "Content-Length: 0"

Example: Upload an object response

HTTP/1.1 201 Created
Last-Modified: Wed, 06 Jan 2016 17:08:31 GMT
Content-Length: 0
Etag: d41d8cd98f00b204e9800998ecf8427e
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx8c18c3e63d2f4c61b9cbe-00568d4a0edfw1
Date: Wed, 06 Jan 2016 17:08:31 GMT

Updating object metadata

To set or update custom metadata for existing objects, you send an HTTP POST request with a valid authentication token. Metadata is set by using the header X-Object-Meta-name: value, where name is the custom name for your metadata and value is the data value.

Note

If an object has custom metadata, when you post new metadata, you must resend any metadata that you want kept with the object or it will be lost.

An HTTP status code of 202 (Accepted) in the response indicates that the metadata for the object was successfully updated.

Example: cURL update object metadata request

curl -i -X POST $API_ENDPOINT/v1/$TENANT_ID/yourContainerName/yourObjectName \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-Object-Meta-ImageType: png" \
-H "X-Object-Meta-ImageSize: 400 MB"

Example: Update object metadata response

HTTP/1.1 202 Accepted
Content-Length: 76
Content-Type: text/html; charset=UTF-8
X-Trans-Id: txffc66e0337ae4cd19e79c-005356a1abdfw1
Date: Tue, 22 Apr 2014 17:06:51 GMT

Retrieving an object

To get the object content and metadata, you send an HTTP GET request with a valid authentication token.

An HTTP status code of 200 (OK) in the response indicates that the object was successfully retrieved.

Example: cURL retrieve an object request

curl -i -X GET $API_ENDPOINT/v1/$TENANT_ID/yourContainerName/yourObjectName \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Retrieve an object response

HTTP/1.1 200 OK
Content-Length: 0
Accept-Ranges: bytes
X-Object-Meta-Imagetype: png
Last-Modified: Tue, 22 Apr 2014 17:06:52 GMT
X-Object-Meta-Imagesize: 400 MB
Etag: d41d8cd98f00b204e9800998ecf8427e
X-Timestamp: 1398186411.61064
Content-Type: image/jpeg
X-Trans-Id: txad3571ebcee24cabb387a-005356a229dfw1
Date: Tue, 22 Apr 2014 17:08:57 GMT

 [ ...object content...]

Deleting an object

To delete an object in a container, you send an HTTP DELETE request with a valid authentication token.

An HTTP status code of 204 (No Content) in the response indicates that the object was successfully deleted.

Both the object data and metadata are removed from the storage system. Object deletion is processed immediately at the time of the request. Any subsequent GET, HEAD, POST, PUT, or DELETE operations return a 404 (Not Found) error (unless object versioning is on and other versions exist). For more information about object versioning, see Object versioning.

Example: cURL delete an object request

curl -i -X DELETE $API_ENDPOINT/v1/$TENANT_ID/yourContainerName/yourObjectName \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Delete an object response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx32fae72bccc94cb68d605-005356a2badfw1
Date: Tue, 22 Apr 2014 17:11:22 GMT

Deleting a container

To delete a container, you send an HTTP DELETE request with a valid authentication token. The container must be empty before you can delete it.

An HTTP status code of 204 (No Content) in the response indicates that the container was successfully deleted.

Example: cURL delete a container request

curl -i -X DELETE $API_ENDPOINT/v1/$TENANT_ID/yourContainerName \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Delete a container response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx4b8836bcc20a457d9bbe4-005356a30fdfw1
Date: Tue, 22 Apr 2014 17:12:47 GMT

Showing account details

To show account details and list containers, you send an HTTP GET request with a valid authentication token. Using the format query parameter on the request causes the list to include details (count, bytes, and name) about each container. Without it, you receive just a list of the container names.

An HTTP status code of 200 (OK) in the response indicates that the account and container details were successfully retrieved.

Example: cURL show account details request

curl -i -X GET $API_ENDPOINT/v1/$TENANT_ID?format=json \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Show account details response

HTTP/1.1 200 OK
Content-Length: 111
X-Account-Object-Count: 573
X-Timestamp: 1369081921.78518
X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284e
X-Account-Meta-Subject: Whaling
X-Account-Bytes-Used: 14268918
X-Account-Container-Count: 2
Content-Type: application/json; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx6c802728f41b4804812ee-005356a3c8dfw1
Date: Tue, 22 Apr 2014 17:15:52 GMT

  [
   {
     "count": 0,
     "bytes": 0,
     "name": "newcontainer"
   },
   {
     "count": 573,
     "bytes": 14268918,
     "name": "wordpressfiles"
   }
 ]

Determining storage usage

To determine how much data you have stored in the system and the number of containers you are using, you send an HTTP HEAD request with a valid authentication token.

An HTTP status code of 204 (No Content) in the response indicates that the storage data was successfully retrieved. The HTTP headers in the response indicate the number of containers in this storage account and the total bytes stored for the entire account.

Example: cURL determine storage usage request

curl -i -X HEAD $API_ENDPOINT/v1/$TENANT_ID \
-H "X-Auth-Token: $AUTH_TOKEN"

Example: Determine storage usage response

HTTP/1.1 204 No Content
Content-Length: 0
X-Account-Object-Count: 573
X-Timestamp: 1369081921.78518
X-Account-Meta-Temp-Url-Key: ed6a04a9f70458575112811a9af5284e
X-Account-Meta-Subject: Whaling
X-Account-Bytes-Used: 14268918
X-Account-Container-Count: 2
Content-Type: text/plain; charset=utf-8
Accept-Ranges: bytes
X-Trans-Id: tx0618e82d44394a6b8c5fb-005356a46fdfw1
Date: Tue, 22 Apr 2014 17:18:39 GMT

CDN-enabling the container and setting a TTL

After creating a container and storing a file in it, you can choose to make the file publicly readable. Because the data in Cloud Files is private, you share your files through the content delivery network (CDN).

To CDN-enable a container, you send an HTTP PUT request with a valid authentication token and with X-CDN-Enabled: True to the CDN management service. (Note that the service access endpoint URL specifies the CDN system.) The default time to live (TTL) value is 72 hours (259200 seconds), with a minimum of 15 minutes (900 seconds) and a maximum of 1 year (31536000 seconds). The following request sets the TTL to 1 week (604800 seconds) with X-TTL:                 604800.

An HTTP status code of 201 (Created) in the response indicates that the container was successfully CDN-enabled.

When the container is CDN-enabled, the service returns its public URI in the X-Cdn-Uri header of the response, and returns the SSL URI in the X-Cdn-Ssl-Uri header of the response. You can combine the public URI with the object name to access the file through the CDN, or you can use the SSL URI with the object name to access the file over a secure SSL connection through the CDN.

Example: cURL CDN-enable container and set TTL request

curl -i -X PUT $API_ENDPOINT/v1/$TENANT_ID/yourContainerName \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-CDN-Enabled: True" \
-H "X-TTL: 604800"

Example: CDN-enable container and set TTL response

Note: X-Cdn-Streaming-Uri and X-Cdn-Ios-Uri links will be discontinued on July 31, 2022.

HTTP/1.1 201 Created
Content-Length: 0
X-Cdn-Ssl-Uri: https://c93f9b29cd3c6bd865ee-24695493c49b279502b280c6ecd262b5.ssl.cf6.rackcdn.com
X-Cdn-Ios-Uri: http://7a701469fe9980c577e9-24695493c49b279502b280c6ecd262b5.iosr.cf6.rackcdn.com
X-Cdn-Uri: http://98199d7b2503ac330f05-24695493c49b279502b280c6ecd262b5.r17.cf6.rackcdn.com
Content-Type: text/html; charset=UTF-8
X-Cdn-Streaming-Uri: http://ce3a54aaf724a75455d6-24695493c49b279502b280c6ecd262b5.r17.stream.cf6.rackcdn.com
X-Trans-Id: txc2b9b4ef77fd45f28c2d2-005356adfchkg1
Date: Tue, 22 Apr 2014 17:59:24 GMT

Viewing CDN-enabled container details

To view details about a container in the CDN, you send an HTTP HEAD request with a valid authentication token to the CDN management service.

An HTTP status code of 204 (No Content) in the response indicates that the container details were successfully retrieved. You can confirm the TTL that you set in CDN-enabling the container and setting a TTL.

Example: cURL view CDN-enabled container details request

curl -i -X HEAD $API_ENDPOINT/v1/$TENANT_ID/yourContainerName \
-H "X-Auth-Token: $AUTH_TOKEN"

Example:View CDN-enabled container details response

Note: X-Cdn-Streaming-Uri and X-Cdn-Ios-Uri links will be discontinued on July 31, 2022.

HTTP/1.1 204 No Content
Content-Length: 0
X-Cdn-Ssl-Uri: https://c93f9b29cd3c6bd865ee-24695493c49b279502b280c6ecd262b5.ssl.cf6.rackcdn.com
X-Ttl: 604800
X-Cdn-Enabled: True
X-Log-Retention: False
X-Cdn-Ios-Uri: http://7a701469fe9980c577e9-24695493c49b279502b280c6ecd262b5.iosr.cf6.rackcdn.com
X-Cdn-Uri: http://98199d7b2503ac330f05-24695493c49b279502b280c6ecd262b5.r17.cf6.rackcdn.com
Content-Type: text/html; charset=UTF-8
X-Cdn-Streaming-Uri: http://ce3a54aaf724a75455d6-24695493c49b279502b280c6ecd262b5.r17.stream.cf6.rackcdn.com
X-Trans-Id: txe291eebdfd96468995a80-005356b167hkg1
Date: Tue, 22 Apr 2014 18:13:59 GMT

Purging an object from a CDN-enabled container

To remove a CDN-enabled object from public access before the TTL expires, you send an HTTP DELETE request with a valid authentication token against the object to the CDN management service (or you can create a support ticket to purge the entire container). Currently, you can perform only 25 purges per account per day.

Note

Remember that you must upload the objects to the container by using one of the storage service access endpoints. The CDN management service references the objects there.

Optionally, you can include a header with an email address to notify that the object was purged.

An HTTP status code of 204 (No Content) in the response indicates that the object was successfully queued to be purged.

Because there are so many edge servers around the world, purging an object might take a long time. Be patient while waiting for the emailed response.

Example: cURL purge an object from a CDN-enabled container request

curl -i -X DELETE $API_ENDPOINT/v1/$TENANT_ID/yourContainerName/yourObjectName /
-H "X-Auth-Token: $AUTH_TOKEN" /
-H "X-Purge-Email: yourEmail@yourDomain.com"

Example: Purge an object from a CDN-enabled container response

HTTP/1.1 204 No Content
Content-Length: 0
Content-Type: text/html; charset=UTF-8
X-Trans-Id: tx45187f74dc814ddeb43af-005356c6e1hkg1
Date: Tue, 22 Apr 2014 19:45:39 GMT

Disabling CDN for a container

To disable use of the CDN for a container, you send an HTTP POST request with a valid authentication token and with X-CDN-Enabled: False to the CDN management service. (Note that the service access endpoint URL specifies the CDN system.)

An HTTP status code of 202 (Accepted) in the response indicates that the request is accepted for processing.

Example: cURL disable CDN for a container request

curl -i -X POST $API_ENDPOINT/v1/$TENANT_ID/yourContainerName \
-H "X-Auth-Token: $AUTH_TOKEN" \
-H "X-CDN-Enabled: False"

Example: Disable CDN for a container response

Note: X-Cdn-Streaming-Uri and X-Cdn-Ios-Uri links will be discontinued on July 31, 2022.

HTTP/1.1 202 Accepted
Content-Length: 76
X-Cdn-Ssl-Uri: https://d0bba87ecb20cfe87c32-58d9a15a50acf66d588aab08348cf859.ssl.cf6.rackcdn.com
X-Cdn-Ios-Uri: http://d03710c19b61b2c12609-58d9a15a50acf66d588aab08348cf859.iosr.cf6.rackcdn.com
X-Cdn-Uri: http://afab448ae0b809160b64-58d9a15a50acf66d588aab08348cf859.r57.cf6.rackcdn.com
Content-Type: text/html; charset=UTF-8
X-Cdn-Streaming-Uri: http://499c627df9227c250afb-58d9a15a50acf66d588aab08348cf859.r57.stream.cf6.rackcdn.com
X-Trans-Id: tx9f451de144d04250a96ed-00535a969bhkg1
Date: Fri, 25 Apr 2014 17:08:43 GMT