Cloud Documentation
Advanced Search


Using Oracle Storage Cloud Service
Close Window

Table of Contents

Show All | Collapse

Accessing Oracle Storage Cloud Service

Interfaces to Oracle Storage Cloud Service

The following table summarizes the interfaces to Oracle Storage Cloud Service: RESTful web service API and the Java library.

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 usage metrics reporting

The URL for the Oracle Storage Cloud Service REST API uses the following format:

https://storage.data-region-code.oraclecloud.com/v1/storage-account/[container-name]/[object-name]

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

  • Object versioning

  • Static website support

  • Cross-origin resource sharing (CORS) support

  • Static large objects

  • Container synchronization

  • Temporary URLs

  • Form post

  • Account ACLs

  • Ratelimits

RESTful web service API is only available over HTTPS.

Managing Containers in Oracle Storage Cloud Service

Managing Objects in Oracle Storage Cloud Service

API Operations for Storage Services in OpenStack Object Storage Service API Reference

Java Library

A Java library that wraps the RESTful web service API.

Most major functionality of the RESTful web service API is available, but not all. For more information about the operations supported by RESTful API and Java library interfaces, see Operations Supported by RESTful API and Java Library

Also provides client-side encryption utilities.

Can be downloaded from Oracle Technology Network (OTN).

Managing Containers in Oracle Storage Cloud Service

Managing Objects in Oracle Storage Cloud Service

Java API Reference for Oracle Storage Cloud Service

Operations Supported by RESTful API and Java Library Interfaces

Use the following table as a guide to select the interface to Oracle Storage Cloud Service:

Operation RESTful API Java Library

Setting account metadata

Yes

No

Creating/deleting/listing containers

Yes

Yes

Updating container metadata — custom

Yes

Yes

Setting special container metadata (ACLs)

Yes

Yes

Setting special container metadata (Quotas)

Yes

No

Creating/deleting/listing objects

Yes

Yes

Creating/deleting bulk objects

Yes

No

Downloading objects

Yes

Yes

Updating object metadata — custom

Yes

Yes

Updating object metadata — special

Yes

No

Copying objects

Yes

No

Encrypting objects

No

Yes

Getting account metadata

Yes

No

Accessing Oracle Storage Cloud Service Using 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 makes use of advanced facets of HTTP such as secure communication over HTTPS, HTTP headers, and specialized HTTP verbs (i.e. PUT, DELETE).

Some applications that meet these requirements are:

  • Curl

  • 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. Please refer to your programming platform's documentation for guidance.

Accessing Oracle Storage Cloud Service Using Java Library

The Java library makes use of 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 with the downloadable Java SDK.

To use the Java library in your own Java applications:

  1. Download the Oracle Storage Cloud Service Java SDK from the Downloads page on OTN at: 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.
  4. Refer to Managing Containers in Oracle Storage Cloud Service and Managing Objects in Oracle Storage Cloud Service for details on how to use the Java library to access the service for your specific needs.

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.

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. 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 REST API

To request an authentication token from the REST API, send a GET HTTP request to https://storage.data-region-code.oraclecloud.com/auth/v1.0. Include your user credentials as the following HTTP headers:

  • X-Storage-User: ServiceName-IdentityDomain:UserName

  • X-Storage-Pass: Password

If your user credentials are not authenticated, the service will return an HTTP response with a status code of 401 and no authentication token will be returned. If your credentials are authenticated, the service will either return your currently active authentication token or generate a new authenticate token. Authentication tokens are returned as the value of the HTTP header X-Storage-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.

To use your authentication token, include it as the value of the X-Storage-Token HTTP header in every HTTP request to the service instance. If your authentication token is not valid, or has expired, the service will return an HTTP response with a status code of 401 and your requested operation will fail. If your 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.

A Curl example 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

> 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

A Curl example 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

> 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 apply an authentication token; the Java library will automatically request and apply it for you.

The Java library will also try to request a new authentication token for you when your 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 a Java snippet for providing user credentials and storing an object:

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);

Note:

In this example, the username and password are in plain text. Oracle recommends that you encrypt the username and password with at least Base64 encoding.