Oracle Cloud Infrastructure Object Storage Classic: Creating Containers Using the REST API

Purpose

This tutorial shows you how to create containers in Oracle Cloud Infrastructure Object Storage Classic via the REST API interface by using the cURL command-line tool.

Time to Complete

Approximately 15 minutes

Introduction

Oracle Cloud Infrastructure Object Storage Classic enables businesses to store and manage digital content in the cloud. Stored objects can be retrieved directly by external clients or by applications running within Oracle Cloud.

A container is a storage compartment that provides a way to organize the data stored in Oracle Cloud Infrastructure Object Storage Classic. Containers are similar to directories, but with a key distinction; unlike directories, containers cannot be nested.

Any user with the Service Administrator role can create containers.

You can access Storage Cloud Service through a REST API or through an official Java library. This tutorial shows you how to create containers via the REST API by using the cURL command-line tool.

Scenario

This tutorial shows you how to create containers in Oracle Cloud Infrastructure Object Storage Classic via the REST API. First, if you don't already have cURL, you must install it. Next, you get an authorization token from Oracle Cloud Infrastructure Object Storage Classic. You use this authorization token to access Oracle Cloud Infrastructure Object Storage Classic to create containers.

Software Requirements

You need a tool to access the REST interface. This tutorial uses cURL, which is free, open software that runs under various operating systems. For the steps to install cURL on a Windows 64-bit machine, click here. Alternatively, click here to install cURL on Cygwin on Windows.

Prerequisites

Before starting this tutorial, you should:

• Have a trial or paid subscription to Oracle Cloud Infrastructure Object Storage Classic.
  

• Know your Oracle Cloud user name, password, and identity domain.

  You can find out these details from the New Account Information email that you received from Oracle Cloud when your user account was set up, as shown in the following example:
  




If you don't have your New Account Information email, contact your account administrator for your Oracle Cloud user name, password, and identity domain. 

• Set the replication policy for your service instance. See Selecting a Data Center for Your Service Instance in Using Oracle Cloud Infrastructure Object Storage Classic.

• Have the Service Administrator role.

  If you aren't sure whether your Oracle Cloud user account has the Service Administrator role, contact your account administrator.

The following is a typical workflow for using Oracle Cloud Infrastructure Object Storage Classic. The focus of this tutorial is on the third step (Create containers).

1. Define users.
2. Define roles, and assign users to roles.
3. Create containers.
4. Store and manage objects in containers.

Oracle Cloud Infrastructure Object Storage Classic requires authentication for any operation against the service instance. Authentication is performed by using an authentication token. Authentication tokens are requested from the service by authenticating your user credentials with the service. All provisioned authentication tokens are temporary and expire in 30 minutes. You must include your current authentication token with every request to Oracle Cloud Infrastructure Object Storage Classic.

1. Request an authentication token by running the following cURL command:

   Note: This example command uses the credentials for the user jack.jones@example.com in a generalized identity domain named myIdentityDomain. If you wish to copy and adapt this example, change it to reflect your Oracle Cloud user name, password, and identity domain. The values that you must change are highlighted in bold in the command example.

   curl -v -s -X GET -H "X-Storage-User: Storage-myIdentityDomain:jack.jones@example.com" -H "X-Storage-Pass: ft7)Dvjo" https://myIdentityDomain.storage.oraclecloud.com/auth/v1.0

   The following is an example of the output of this command, with certain key lines highlighted. Note that if the request includes the correct credentials, it returns the HTTP/1.1 200 OK response.

   



2. From the output of the command you just ran, note the following:
   
   
   • The value of the X-Storage-Url header.

     This value is the REST endpoint URL of the service. You'll use this URL in the next step to create the container.

     In the example output, the service REST endpoint is https://storage.us2.oraclecloud.com/v1/Storage-<identity_domain>.

     Note: The cURL command examples in this tutorial are for requests to REST URLs for a metered Oracle Cloud Infrastructure Object Storage Classic subscription. For requests to an nonmetered Oracle Cloud Infrastructure Object Storage Classic subscription, the format of the REST URLs is different from that for metered subscriptions. See About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources in Using Oracle Cloud Infrastructure Object Storage Classic.

   • The value of the X-Auth-Token header.

     This value is the authentication token, which you'll use in the next step to create the container. Note that the authentication token expires after 30 minutes, after which you should request a fresh token.

     In the example output, the authentication token is AUTH_tk23be53ac28c3e443de38367f87643eb9.

In this section, you create a container named myFirstContainer .

Run the following cURL command:

curl -v -s -X PUT -H "X-Auth-Token: AUTH_tk85388cfc91ece053145e3ff386e96552" https://storage.us2.oraclecloud.com/v1/Storage-myIdentityDomain/myFirstContainer

Note: When you run this command,
- Replace the value of the X-Auth-Token header with the authentication token that you obtained earlier.
- Change https://storage.us2.oraclecloud.com/v1/Storage-myIdentityDomain to the X-Storage-Url header value that you noted while getting an authentication token.
- And change myFirstContainer to the name of the container that you want to create.

If the request is completed successfully, it returns the HTTP/1.1 201 Created response, as shown in the following sample output.

In this section, you verify the existence of the container named myFirstContainer that you created earlier.

Run the following cURL command:

curl -v -s -X GET -H "X-Auth-Token: AUTH_tk85388cfc91ece053145e3ff386e96552" https://storage.us2.oraclecloud.com/v1/Storage-myIdentityDomain/myFirstContainer

Note: When you run this command,
- Replace the value of the X-Auth-Token header with the authentication token that you obtained earlier.
- Change https://storage.us2.oraclecloud.com/v1/Storage-myIdentityDomain to the service REST endpoint URL that was returned in the authentication request.
- And change myFirstContainer to the name of the container that you want to verify.

If the request is completed successfully, it returns the HTTP/1.1 204 No Content response, as shown in the following sample output. This response indicates that there are no objects yet in your new container.

The X-Container-Object-Count and X-Container-Bytes-Used headers in this example have the value zero, indicating again that there are no objects in the container. As you upload data to the container, objects are created, and these headers will then show non-zero values.

The X-Container-Read and X-Container-Write headers represent Access Control Lists (ACLs) specifying the user roles that have read and write access, respectively, to the container. To learn more about controlling access to containers by using ACLs, see the Restrict Read and Write Access to Containers Using the REST API tutorial.

In this tutorial, you learned to:

1. Get an authentication token from Oracle Cloud Infrastructure Object Storage Classic.
2. Create a container.
3. Verify that the container was created.

Credits

• Curriculum Developer: Kumar Dhanagopal
• Contributors: Rehan Iftikhar, Ben Gelernter