Accessing Oracle Storage Cloud Service

You can access Oracle Storage Cloud Service using either the RESTful web service API or the Java library.

Interfaces to Oracle Storage Cloud Service

The following table summarizes the interfaces to Oracle Storage Cloud Service.

Interface Description More Information

RESTful Web Service API

Oracle Storage Cloud Service provides REST APIs based on OpenStack Swift. The following major additions have been made:

  • Centralized identity management across Oracle Cloud
  • Centralized reporting of usage metrics

Oracle Storage Cloud Service does not support the following OpenStack Swift features:

  • Object versioning
  • Static website support
  • Cross-origin resource sharing (CORS) support
  • Static large objects
  • Container synchronization
  • Temporary URLs
  • Form post
  • Account ACLs
  • Rate limits

The RESTful web service API is available only over HTTPS.

Java Library

A Java library that wraps the RESTful web service API.

The Java library supports most of the major features of the RESTful web service API.

The Java library also provides client-side encryption utilities.

Tasks Supported by the RESTful API and Java Library Interfaces

Use the following table as a guide to select the interface to Oracle Storage Cloud Service. Yes indicates that the task can be performed using the interface.

Task RESTful API Java Library

Setting account metadata

Yes

No

Getting account metadata

Yes

No

Creating, deleting, and listing containers

Yes

Yes

Setting custom metadata for containers

Yes

Yes

Setting container ACLs

Yes

Yes

Setting container quotas

Yes

No

Creating, deleting, and listing objects

Yes

Yes

Bulk-creating and bulk-deleting objects

Yes

No

Downloading objects

Yes

Yes

Updating custom metadata for objects

Yes

Yes

Updating special metadata for objects

Yes

No

Copying objects

Yes

No

Encrypting objects

No

Yes

Accessing Oracle Storage Cloud Service Using the REST API

The REST API can be accessed from any application or programming platform that correctly and completely understands the Hypertext Transfer Protocol (HTTP) and has Internet connectivity. The REST API uses advanced facets of HTTP such as secure communication over HTTPS, HTTP headers, and specialized HTTP verbs (PUT, DELETE).

Some applications that meet these requirements are:

  • cURL — cURL is a command-line tool that you can use to invoke REST API calls by sending HTTP requests.

    To use cURL, see http://curl.haxx.se and the tutorial, Installing cURL on Cygwin on Windows.

  • Web browsers — Support varies across vendors. Some browser plugins may be needed for full support.

Many programming platforms (Java, Ruby, Perl, PHP, .NET, and so on) also meet these requirements, although some may require the use of third party libraries for full support. See your programming platform's documentation for guidance.

About REST URLs for Oracle Storage Cloud Service Resources

Accounts, containers, and objects in an Oracle Storage Cloud Service instance are represented as REST resources and are accessible through HTTP uniform resource locators (URLs).

URL for the Account

The URL for the account is also the REST API endpoint of the service instance. You can find the REST API endpoint in the Oracle Cloud My Services page, under the Additional Information section, in the Service REST Endpoint field.

The URL for the Oracle Storage Cloud Service REST API endpoint is in the following format:
  • Global namespace URL for all customers: https://identityDomainName.storage.oraclecloud.com/v1/Storage-identityDomainName
  • Data center-specific URL for all customers: https://dataCenterCode.storage.oraclecloud.com/v1/Storage-identityDomainName
  • URL in early releases of Oracle Storage Cloud Service:
    • Metered subscription: https://storage.dataCenterCode.oraclecloud.com/v1/Storage-identityDomainName
    • Nonmetered subscription: https://storage.dataCenterCode.oraclecloud.com/v1/serviceInstanceName-identityDomainName

    Note:

    If your client applications use a URL from an early release of Oracle Storage Cloud Service, you can update the applications to use the global namespace URL.
In these URL formats,
  • identityDomainName is the identity domain in which the service instance is provisioned.
  • dataCenterCode is the identifier of the data center in which the service instance is provisioned.
    • Chicago, Illinois, U.S.A: us2
    • Ashburn, Virginia, U.S.A: us6
  • serviceInstanceName is the customer-specified name of the service instance.
For example, for a service instance named myStorage2 that is provisioned in the myIdentity3 domain in the us2 data center, the REST API endpoint URLs would be:
  • Global namespace URL for all customers: https://myIdentity3.storage.oraclecloud.com/v1/Storage–myIdentity3
  • Data center-specific URLs for all customers: https://us2.storage.oraclecloud.com/v1/Storage-myIdentity3
  • URL in early releases of Oracle Storage Cloud Service:
    • Metered subscription: https://storage.us2.oraclecloud.com/v1/Storage-myIdentity3
    • Nonmetered subscription: https://storage.us2.oraclecloud.com/v1/myStorage2-myIdentity3

URLs for Containers

Containers are resources within an account.

Given the sample REST API endpoint URL above for a metered subscription, the URL for a container named myContainer4 would be https://storage.us2.oraclecloud.com/v1/Storage–myIdentity3/myContainer4

Given the sample global namespace REST API endpoint URL above, the URL for a container named myContainer4 would be https://myIdentity3.storage.oraclecloud.com/v1/Storage–myIdentity3/myContainer4

URLs for Objects

Objects are resources within containers.

Given the sample REST API endpoint URL above for a metered subscription, the URL for an object named myObject5 in the myContainer4 container would be https://storage.us2.oraclecloud.com/v1/Storage–myIdentity3/myContainer4/myObject5

Given the sample global namespace REST API endpoint URL above, the URL for an object named myObject5 in the myContainer4 container would be https://myIdentity3.storage.oraclecloud.com/v1/Storage–myIdentity3/myContainer4/myObject5

Note:

These URLs are valid for any object in a Standard or Archive container. To restore and track restoration progress of an object in an Archive container, the URL for an object named myObject5 in the myArchiveContainer5 container would be https://myIdentity3.storage.oraclecloud.com/v0/Storage–myIdentity3/myArchiveContainer5/myObject5. Note the v0 API version in the URL.

Accessing Oracle Storage Cloud Service Using the Java Library

The Java library uses the REST API. So the Java library, too, requires Internet connectivity.

The Java library requires Java Runtime Environment (JRE) version 1.6 or later. The Java library has several runtime-dependent Java libraries, all of which are included in the downloadable Java SDK.

To use the Java library in your own Java applications:

  1. Download the Oracle Storage Cloud Service Java SDK from: http://www.oracle.com/technetwork/topics/cloud/downloads/cloud-service-java-sdk-2121032.html
  2. Extract the Java library's classes and runtime dependencies somewhere onto your Java application's class path.
  3. Import the Java library's classes and interfaces into your Java application.
For information about using the Java library to perform specific operations for containers and objects, see Managing Containers in Oracle Storage Cloud Service and Managing Objects in Oracle Storage Cloud Service.

Authenticating Access to Oracle Storage Cloud Service

Oracle Storage Cloud Service requires authentication when executing operations against your service instance. Authentication is provided to the service instance in the form of an authentication token.

You request an authentication token from the service by sending your user credentials to the service. Authentication tokens are temporary and expire in 30 minutes. This is a session time out and not an idle time out, which means that tokens expire even if they are in use. You must include your current authentication token with every operation against your service instance.

Topics:

Authenticating Access When Using the REST API

To request an authentication token, send a GET request to the following URL:

  • Global namespace URL for all customers: https://identityDomainName.storage.oraclecloud.com/auth/v1.0
  • Data center-specific URL for all customers: https://dataCenterCode.storage.oraclecloud.com/auth/v1.0
  • URL in early releases of Oracle Storage Cloud Service: https://storage.dataCenterCode.oraclecloud.com/auth/v1.0

    Note:

    If your client applications use a URL from an early release of Oracle Storage Cloud Service, you can update the applications to use the global namespace URL.
In these URL formats,
  • identityDomainName is the identity domain in which the service instance is provisioned.
  • dataCenterCode is the identifier of the data center in which the service instance is provisioned.
    • Chicago, Illinois, U.S.A: us2
    • Ashburn, Virginia, U.S.A: us6

Include your user credentials in the following headers:

  • X-Storage-User
    • Syntax for metered subscriptions: X-Storage-User: Storage-identityDomainName:userName

    • Syntax for nonmetered subscriptions: X-Storage-User: serviceInstanceName-identityDomainName:userName

  • X-Storage-Pass: password

You can find out your user name, password, and identity domain name from the “New Account Information” email that you received from Oracle Cloud when your account was set up, as shown in the following example:
Description of GUID-45E9886F-F328-48BD-8788-DDD8EC0FE3CC-default.gif follows
Description of GUID-45E9886F-F328-48BD-8788-DDD8EC0FE3CC-default.gif

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

If your user credentials are not authenticated, the service returns an HTTP response with a status code of 401 and no authentication token is returned.

If the credentials are authenticated, the service either returns the currently active authentication token or generates a new authenticate token. Authentication tokens are returned as the value of the HTTP header X-Auth-Token in the HTTP response. Requesting an authentication token with credentials that already have an active authentication token will not extend the expiration time of the existing authentication token.

Here’s an example of a cURL command for requesting an authentication token:

curl -v -X GET \
     -H "X-Storage-User: myService-myIdentityDomain:myUsername" \
     -H "X-Storage-Pass: myPassword" \
     https://storage.us2.oraclecloud.com/auth/v1.0

The following is an example of the output of this command:

> GET /auth/v1.0 HTTP/1.1
> Host: storage.us2.oraclecloud.com
> Accept: */*
> X-Storage-User: myService-myIdentityDomain:myUsername
> X-Storage-Pass: myPassword

< HTTP/1.1 200 OK
< X-Storage-Url: https://storage.us2.oraclecloud.com/v1/myService-myIdentityDomain
< X-Storage-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
< X-Trans-Id: txba4aa8f776164c33b7aa587554c29fb6
< Content-Length: 0
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Type: text/plain
< Content-Language: en

To use your authentication token, include it as the value of the X-Auth-Token HTTP header in every HTTP request to the service instance. If your authentication token is not valid, or has expired, the service returns an HTTP response with the status code 401 and the requested operation will fail. If the authentication token has expired, you must request a new token. If you are reading publicly accessible objects, you do not need to provide an authentication token in your HTTP request; anonymously accessible objects do not need an authentication token.

Here’s an example of a cURL command for storing an object in an account using an authentication token:

curl -v -X PUT \
     -H "X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6" \
     -d "Hello, World!" \
     https://storage.us2.oraclecloud.com/v1/myService-myIdentityDomain/myContainer/myObject

The following is an example of the output of this command:

> PUT /v1/myService-myIdentityDomain/myContainer/myObject HTTP/1.1
> Host: storage.us2.oraclecloud.com
> Accept: */*
> X-Auth-Token: AUTH_tk209f7f2ea1265a0d3f29d28a2dc8ced6
> Content-Length: 13
> Content-Type: application/x-www-form-urlencoded

< HTTP/1.1 201 Created
< Content-Length: 0
< Etag: 65a8e27d8879283831b664bd8b7f0ad4
< Content-Type: text/html; charset=UTF-8
< X-Trans-Id: tx287a1a8e33cc45e5a1431817e3e87621
< Cache-Control: no-cache
< Pragma: no-cache
< Content-Language: en

Authenticating Access When Using the Java Library

When using the Java library, you do not need to manually request and use an authentication token; the Java library will automatically request and use it.

The Java library will also try to request a new authentication token when the current authentication token expires.

When using the Java library, you must pass your user credentials to a CloudStorageConfig object. The CloudStorageConfig object is then passed to a CloudStorageFactory object and, upon successful authentication, ultimately returns a CloudStorage object. The CloudStorage object provides the methods for all supported functionality to the service instance.

The following is an example of Java code for providing user credentials and creating an object. The values used in this example are illustrative. While developing Java code to use Oracle Storage Cloud Service, ensure that the code complies with the IT security standards and requirements of your organization.

CloudStorageConfig myConfig = new CloudStorageConfig();
 myConfig.setServiceName("myService-myIdentityDomain")
   .setUsername("myUsername")
   .setPassword("myPassword".toCharArray())
   .setServiceUrl("https://storage.us2.oraclecloud.com");
 CloudStorage myConnection = CloudStorageFactory.getStorage(myConfig);
 FileInputStream fis = new FileInputStream("hello_world.txt");
 myConnection.storeObject("MyContainer", "hello_world.txt", "text/plain", fis);
To identify the service URL and service name (for the setServiceName and setServiceUrl methods in this code example) of your Oracle Storage Cloud Service instance:
  1. Sign in to the Oracle Cloud My Services application. See Signing In to the My Services Application in Getting Started with Oracle Cloud.
    The My Services Dashboard is displayed. It lists the services that are assigned to your account.
  2. Look for Oracle Storage Cloud Service.
  3. From the Actions You can select the action you would like to perform from the Actions menu. menu, select View Details. Alternatively, click the Oracle Storage Cloud Service link in the Dashboard page.
    On the resulting page, look for the REST Endpoint field. You can see the details of the service URL and service name of your Oracle Storage Cloud Service instance, as highlighted in the following screenshot.

    In this example, which is for a metered account, the following are the service URL and name:

    • Service URL: https://storage.us2.oraclecloud.com

    • Service Name: Storage-myIdentityDomain